API Technology Explained: Definition, Types, and Documentation

A cookbook. A restaurant menu. Human interaction. All of these are good analogies of API. This abbreviation is commonly used in the realm of software development, but what does it actually mean? In this article, we will look at definition of API, its types and documentation. 

So what is API? API is an Application Programming Interface that enables interaction, access, and data / functionality exchange between two separate software systems. In essence, an API mediates the connection between the systems via an interface, creating an environment for their interaction. There are several types of API, such as database API, operating system API, but the most common ones are web API. 

To back up the human interaction analogy, API is a kind of communication channel that allows two applications to communicate via a machine-readable interface. Perhaps the most recognized example of API is one that allows users to log in using our Google account. In this case, an API facilitates the connection to the database of these systems to get the required data. For instance, by integrating Facebook API, your app users will not have to fill out long contact forms because Facebook provides this data by means of API. Instagram uses camera API to take pictures and Uber identifies a user’s location by connecting to geolocation API from Google Maps. In fact, most apps that we use every day have integrations with other services, thus they rely on API under the hood. 

On a technical front, an API is a set of tools, communication protocols, and subroutine definitions for building software (a.k.a a cookbook). It’s a resource for developers that lets them work without digging into the source code of a program. For example, a developer can use the interface to retrieve the required data or functionality. 

An API consists two entities:

• Specification. This is basically a contract that describes data exchange terms. As such, an API answers the question of ways how to retrieve the data. 
• An interface that complies with a specification. It can be SOAP, REST interface as well as another API. 

How do they work? 

A popular analogy is a restaurant. When ordering at a restaurant, you are given a menu with dishes listed. We usually go about this in one way – by saying our order and having a dish prepared. 

In software development, a menu stands for an interface. Everything listed here is what you can obtain by ordering. What’s not on the menu cannot be served by default. An API helps a software system to request and receive specific data types from another software system. A waiter facilitates the food delivery process, acting as a mediator between kitchen staff and a visitor. To tie it back to API, when an application needs to access data from another application, it calls its API, specifying what data it needs to retrieve. The other application provides data requested by the first application. 

Application Programming Interfaces are used for multiple purposes. For one, they let developers create feature-rich products faster. With an API, they can enrich products with additional functionality without having to develop it from the ground up. APIs also facilitate software support. Developers use a trusted API, while adding their own code to connect their software to another one. In this case, they only need to support the code written by them. 

What types of API are there?

The matter is, APIs come in many forms. The developers can choose from a range of protocols and standards when creating a new one, depending on the type of API they want to create and for what purpose.

• Internal. These are available to the company’s employees internally. This type of APIs is used to optimize work processes and reduce costs within an organization. 
• Partner. Available to business partners and users of a product / service and used to optimize processes and development. 
• Public. Available to anyone and are used to create new services and popularize the existing solution. Public APIs can be open (license-free) and commercial.

The most common are Web APIs, meaning APIs designed for the web. Web APIs are used as a platform for creating HTTP services. These APIs are used to add more functionalities on web apps like Google Maps or authorization via socials. 

Web APIs can be divided into the following types according to their specifications:

• RPC (Remote Procedure Call)
• SOAP (Simple Object Access Protocol) 
• REST (Representational State Transfer) 

Protocols aim to achieve a certain standard of data exchange between different systems, OS, languages, and technologies so that the systems can communicate smoothly. 

Let’s have a closer look at these protocols: 

Remote Procedure Call (RPC)

Some Web APIs follow the data exchange principles based on a RPC, a protocol that specifies the interaction between client-server based applications. In this standard, a client requests and receives data from server. 

Simple Object Access Protocol (SOAP)

SOAP is a protocol for exchanging structured information in a distributed systems based on XML (extensible markup language) format. SOAP entails a set of syntax rules for request and response. This way, SOAP APIs enables XML communication between software via HTTP. SOAP is a highly secure data transmission protocol used in enterprise, payment systems, CRM, financial serviced, and telecommunication. 

Representational State Transfer (REST)

REST is a software architecture style that is oriented at using HTTP as a transport protocol. Web APIs that comply with the six constraints of REST are called RESTful. World Wide Web is the most popular REST system. Another good example of a RESTful API is Twitter API. 

Addition: GraphQL

GraphQL is an open-source query language for API developed by Facebook in 2015. It was created as an alternative to REST for developing and using application programming interfaces. GraphQL allows the client to specify exactly what data they need and facilitates the aggregation of data from multiple sources. GraphQL is a good way to speed up development and create more powerful APIs. 

API documentation

API documentation is a set of rules required to work with the API, including information about classes, functions, arguments, and more. Despite that web APIs come in all shapes and forms, there are some standards that every API must follow. A well-rounded documentation consists of:

• Authentication guide
• Quickstart guide 
• Endpoint definitions 
• Code snippets 
• Example responses

Additionally, there are seven essentials every web API should have in its documentation. 

Authentication 

Authentication is basically the process of logining into the API. Authentication methods vary from simple to complex, each with their own and rules. An example is HTTP Basic Authentication, one of the easiest methods of API authentication. 

HTTP Call Types

Documenting HTTP call types is important as much as authentication rules. Since web APIs interact with a number of HTTP call methods, documenting these methods and how they are used is essential. As such, every common call types (that includes get, post, put, patch, delete) should be defined. 

Endpoints

Endpoints are the starting point of a user’s interaction with an internal system, so they should also be well-documented. Their documentation should entail what an endpoint does and how it is related to the rest of them. Ultimately, it makes sense to create a map of endpoints. 

URI Structures

It is also important to document the structure and methods for each URI within the API. Describing all functions in detail facilitates usage of an API.

Human Readable Method Descriptions

This one is a simplified human-centric form of description as opposed to machine-readable documentation and description for technology-savvy users. Thus, it can be regarded as an addition to more technical documentation. 

Requests and Examples

Documenting what URL requests look like with examples makes a lot of sense. For one, displaying an example of API calls is more actionable. It’s also a way of user onboarding that helps them understand complex requests. Finally, it’s a way to handle errors by comparing with an example users can fix their failed requests. 

Expected Responses

Expected response documentation brings a lot of value since they allow a user to expect a given response, in a given language and format, as opposed to convoluted responses with numerous functions and data wrappers. 

 Afterword

API integration is behind the scenes of many software development companies, which lets them reduce customer churn, accelerate time-to-market, and achieve product stickiness. As such, it is important to select the right APIs and understand how to make the most of them. If you are looking for a technology partner, our team at NCube can help you with API integration and development. Contact us for consultation.