# Application Programming Interface

## Summary


The Application Programming Interface (API) is a technology that allows two software components to interact with one other without knowing how they're implemented.  The term "application" in API refers to any software that performs a certain activity. The agreement between two such software to interact is known as the "interface". 

In any API, one entity provides the API via an endpoint and another entity consumes the API by making an API call. An API's documentation or specification will describe how to use it, how it is organised, and how it interacts with other APIs. 

For instance, suppose each airline operator exposes its data via an API. An online ticketing portal gathers data from various airlines via these APIs and then shows aggregated data to end users. Users can compare prices, view schedules and book tickets.

## Discussion

### Why do we need APIs?

APIs connect different applications. It can connect two or more components from separate applications to perform some functions and share data. APIs are useful for building strong and robust applications since they allow developers to reuse capabilities while also reducing code size, which enhances user experience and application security. 

Many businesses use API to provide a smooth experience of using backend architecture, allowing users to interact with them more easily. It's often shared with third-party developers so that they can integrate it with other services. It also reduces the issues of incompatibility and eliminates the need for recreating it for various platforms conversions which is expensive. 

APIs provide flexibility to businesses by allowing them to easily connect with their new partners or provide new services from existing products. They can easily switch to create new products, which could potentially generate large profits. 

Ultimately, APIs are designed for machines, not humans. API is not directly related to UI/UX. In the world of IoT and automation, APIs are becoming critical.  Siemens has patented the concept of human programming interfaces for future human-machine interaction in an automation environment. 


### What is an API-first approach?

The concept of API-first started with the adoption of microservices in which applications are built as independent components and coupled together via API. Major companies such as Netflix, Amazon, and PayPal have moved to microservices architecture for their applications with great success. 

API-first refers to giving APIs first priority in the development of software products. There's no widely accepted definition of the term API-first. This API-first strategy improves developer experience by introducing consistency, as they employ the same format and styles throughout the development. A style guide may be utilised by teams throughout since it documents the status code, error handling techniques, versioning strategies, and other API specifics. It ensures the consistency and reusability of all APIs.  

The OpenAPI Specification is the most extensively used API specification language (also known as the Swagger Specification). While alternative API definition languages, such as RAML and API Blueprint, exist OpenAPI has become the standard practice. 


### What are the characteristics of a good API?

We note three characteristics:

    + **Effective Documentation**: API documentation is a written reference for effectively utilising API functionalities. It should be simple for developers to grasp. A solid API documentation should be created for users who are unfamiliar with that specific API. It should also include examples describing usage of various functionality in an API created through documentation software.
    + **Error Handling**: Precise usage of error codes is must in an API. Error codes in responses help clients to understand the exact cause of the problem. Appropriate HTTP status code will also provide a positive user experience. Besides alerting them, these assist clients in fixing the problem. Generally, error codes 400-499 imply client-side errors, while 500-599 imply server-side errors.
    + **Authorization and Authentication**: Authorization is a process of evaluating access privileges to an endpoint or a method of an API, whereas authentication is the process of validating credentials like user session, id, or password provided through the request.

### What is meant by implementation hiding in API design?

In the restaurant example above, a customer interacts only with the waiter and not the cook. The waiter informs the cook the order, picks up the order when it's ready and serves it to customer. The customer has no idea what happened in the middle or how the meal was prepared by the cook. 

Similarly in software, an ideal API will hide its implementation details. It will provide a generic solution without exposing implementation. This is called information hiding. API users don't care about inner workings. All they expect is simplicity of use. Furthermore, by concealing implementation details the API provider can subsequently alter or improve inner workings without impacting client applications that consume the API. This also builds trust with clients. 

Sometimes an API fails to properly hide underlying implementation details. We call this a leaky abstraction, which is something to be avoided. 


### What are the different types of API?

Categorised by use cases, we note the following:

    + **Operating System APIs**: These APIs ensure tasks run inside operating systems smoothly. It interacts with its own resources and services. These APIs will be specific to each operating system. Linux employs kernel-user space API, while Microsoft uses Windows API.
    + **Remote APIs**: Provider and consumer of the API are on different machines. They communicate over a local network and/or the internet. These APIs are typically developed in web standards. Java Database Connectivity API is a remote API in Java. Even though not all remote APIs are web APIs, they can be thought of as remote APIs.
    + **Web APIs**: These primarily use HTTP to receive requests/responses in the form of XML or JSON.  These are often synchronous and stateless.
    + **Database APIs**: These APIs are used as interface between database management systems and applications in order to query, read, write, or modify data on a remote database.  In general, backend APIs are asynchronous and stateful. They facilitate complex integrations.
    + **Language APIs**: Programming languages provide built-in APIs such as classes, methods, macros and even extensive libraries, such as Collections in Java and Standard Template Library (STL) in C++.

### What are the different types of release policies for an API?

Here are some API types organised by release policy rather than design style:

    + **External or Public API**: It's extensively used by third-party developers or users external to the organization. It's built with most robust technologies keeping high consumption in mind. Google Maps API is one example of Public API which is widely used by delivery apps and ride-sharing companies for directions and real-time location tracking.
    + **Internal or Private API**: It's for internal use typically within a team or organisation. It's a common type of API that is simple to develop as it doesn't require robust infrastructure for small consumer base. Because of recent practices like DevOps and microservice architecture, this type of API is essential.
    + **Partner API**: This is neither entirely private nor completely public. These APIs can be accessed by people outside the organisation or team but with special authorization. Examples include Twitter or AirBnB, where access is restricted to authorised users only.
    + **Composite API**: Composite APIs merge many API data requests into one. It saves data usage in applications by reducing the amount of API requests.


## Milestones

1960

Developers start building libraries to share procedural language capabilities with other developers. Because API has no formal definition, this is a conceptual application. These languages have subroutines, which are chunks of code that can be invoked and collaborated on by other programmers. It can be used without exposing the internal code of the libraries. 

Dec  
1968

In the paper titled *Data structures and techniques for remote computer graphics*, Cotton and Greatorex use the term **Application Program Interface** (without -ing suffix). This paper describes independent hardware for computer graphics system. 

May  
1981

In a dissertation, Nelson introduces a new method of API interaction called **Remote Procedure Call (RPC)**. It can communicate with a piece of code on another remote server, just like a local computer. 

1988

**Portable Operating System Interface (POSIX)** standard is introduced to solve the portability issues. It defines an interface between hardware and operating system, specifying application programming interfaces (APIs) at the source level.  

1990

Malamud, in his book *Analyzing Novell Networks* defines API as "a set of services available to a programmer for performing certain tasks." 

Oct  
1991

Object Management Group (OMG) defines the Common Object Request Broker Architecture (CORBA) as a standard. In CORBA, software components are treated as objects running on multiple systems and able to communicate with one another. An object could be written in any programming language. Objects are specified using an Interface Definition Language (IDL) syntax. The version 1.0 release supports C Language mapping.  CORBA uses Object Request Broker (ORB) to communicate between client and server applications. 

Sep  
1996

Microsoft introduces Distributed Component Object Model (DCOM), an improved version of the older Component Object Model (COM) for Windows 95. This enables communication between components like as ActiveX controls, scripts, and Java applets that exist on several machines on a LAN, WAN, or on the Internet through the use of Remote Procedure Calls (RPCs), allowing distributed communication across multiple networks. 

Nov  
1999

Microsoft, UserLand Software and DevelopMentor jointly release **Simple Object Access Protocol (SOAP)** which uses Extensible Markup Language (XML) syntax to send RPC messages over HTTP. SOAP links COM and DCOM objects and runs natively in Windows 95, 98 and NT. It can also connect with Internet Explorer and Java. 

2000

Roy Thomas Fielding, a Ph.D scholar, introduces the concept of Representational State Transfer (REST) in his dissertation. It's a network-based architectural style that later popularizes the usage of web APIs. 

Feb  
2000

Salesforce launches its web API at the IDG Demo conference. It's a enterprise-class, web-based Salesforce automation offered as a "Internet as a Service." In December, eBay launches their API to a selected number of developers and partners. 

Jul  
2002

Amazon Inc launches Amazon.com Web Services API. This enables developers or third-party websites to display Amazon products in their websites in XML format. 

Mar  
2008

Apple releases iPhone 2.0 software. This includes the iPhone Software Development Kit (SDK). The SDK comprises a set of APIs and tools for developing iPhone and iPod applications. It also includes Core OS, Core Services, Media, and Cocoa Touch interfaces. 

Feb  
2015

Google open sources **gRPC**, a framework for handling remote procedure calls. The underlying transport protocol is HTTP 2.0. gRPC differs from HTTP in that it is based on the Remote Procedure Call (RPC) model, in which addressable "entities" of a collection are called procedures and the data is hidden behind the procedures. In contrast, in HTTP, addressable entities are called "data entities" and their behaviour is hidden behind data. Because gRPC is founded on HTTP 2.0 standards, it has many more capabilities that help speed up services while conserving resources such as energy and data. 

Sep  
2015

When Facebook developers attempt to build native Facebook implementations for iOS and Android instead of using the mobile-webview, which had some restrictions, they start to run into a lot of problems. They tried to use RESTful architecture, but it didn't meet their needs because they wanted the data to look like a graph of objects and models. They needed an API to display the newsfeed, which had previously been displayed as HTML. As a result, they create **GraphQL**, a new project that defines data query language in a new way to assist product designers.  

Jun  
2019

According to Programmable Web, an API research website, its API directory surpassed 22,000 APIs. Every month, an average of 220 APIs are introduced, representing a 30% increase over the previous four years. API adoption has been growing since 2005. API developers have begun to offer APIs in alternative architectures such as GraphQL and gRPC in addition to traditional REST, resulting in a larger directory.