“API” as a case study…

Do you work in tech or elsewhere, do you have a rather vague or incorrect idea about what this fairly common term means.

Well, I’m an apprentice in the field of tech, and Yes! I used to have both incorrect and vague ideas about the term API at a certain point in time, but as of this moment, I believe I understand it properly and I'm willing to help you understand it as well, by putting you through the whats, hows, and whens of an API, its types, components, specifications, and documentation.
Let’s get to it then…

What’s an API?

Communication. As humans, we express our thoughts, ideas, and needs through language(either spoken or written), gestures, or facial expressions.
Interacting with computers, websites, and apps we make use of the user interface components — a screen with a menu and graphical elements, a keyboard, and a mouse.

When it comes to software or their elements, they don’t need a graphical user interface to communicate with each other. Software products exchange data and functionalities via sets of intermediaries which are machine-readable interfaces otherwise known as APIs — an acronym for Application Programming Interfaces.

How?

An API is a set of programming codes that enables data transmission between one software product and another.

Press enter or click to view image in full sizeImage representation of how the API works by Yasir Gaji

When you use an application on your mobile phone, the application connects to the Internet and sends data to a server. The server then retrieves that data, interprets it, performs the necessary actions, and sends it back to your phone. The application then interprets that data and presents you with the information you wanted in a readable way. This is what an API is — all of this happens via API.

When?

APIs originated in the 1940s, by British computer scientists Maurice Wilkes and David Wheeler at the time they worked on a modular software library EDSAC (Electronic delay storage automatic calculator) an early computer…..wait! scratch that, that’s not the when I’m to put you through.

The “WHEN” is to emphasize better when its used in the process of how it works take for instance you’re sitting at a table in a restaurant with a menu of choices to order from(request). The kitchen(data base) far away(remote) from where you are is the part of the “system” that will prepare your order. What is missing is the critical link to communicate your order to the kitchen and deliver your food back to your table. That’s where the waiter or API comes in. The waiter is the messenger — or API — that takes your request or order and tells the kitchen — the system — what to do. Then the waiter delivers the response back to you. Which in this case, the food.
So “when” is API used, simply put it’s used for the remote integration of data (request | response).

Types of APIs

We have two classifications, API types by release policies and API types by use cases.

There are three approaches to API release policies, which I call the API trinity.

Press enter or click to view image in full sizeThe API Trinity Image By Yasir Gaji

Private APIs. These application software interfaces are designed for improving solutions and services within an organization. In-house programmers or engineers may use these APIs to integrate a company’s IT systems or applications, build new systems or customer-facing apps leveraging existing systems. Even if apps are publicly available, the interface itself remains available only for those working directly with the API publisher.

Partners APIs. Partner APIs are openly promoted but shared with business partners who have signed an agreement with the publisher. The common use case for partner API is software integration between two parties. A company that grants partners with access to data or capability benefits from extra revenue streams. At the same time, it can monitor how the exposed digital assets are used, ensure whether third-party solutions using their API provide decent user experience, and maintain corporate identity in their software.

Public APIs. Also known as developer-facing or external, these APIs are available for any third-party developers. A public API program allows for increasing brand awareness and receiving an additional source of income when properly executed.

API types by use cases.
APIs can be classified according to the systems for which they are designed, which I call the API cardinal points.

Press enter or click to view image in full sizeTHE API CARDINAL POINTS IMAGE BY Yasir Gaji

Database APIs. Database APIs enable communication between an application and a database management system. Developers work with databases by writing queries to access data for reuse purposes.

Operating systems APIs. This type group of APIs defines how applications use the resources and services of operating systems. Every OS has its set of APIs, for instance, Windows API or Linux API (kernel–user space API and kernel internal API).

Remote APIs. Remote APIs define standards of interaction for applications running on different machines. In other words, one software product accesses resources located outside the device that requests them, which explains the name. Since two remotely located applications are connected over a communications network, like the internet, most remote APIs are written based on web standards. Java Database Connectivity API and Java Remote Method Invocation API are two examples of remote application programming interfaces.

Web APIs. This API class is the most common. Web APIs provide machine-readable data and functionality transfer between web-based systems which represent client server architecture. These APIs mainly deliver requests from web applications and responses from servers using Hypertext Transfer Protocol (HTTP).

Developers can use web APIs to extend the functionality of their apps or sites. For instance, the Pinterest API comes with tools for adding users’ Pinterest data like boards or Pins to a website. Google Maps API enables the addition of a map with an organization’s location.

Most businesses use more than one API to connect applications and share information.

Components.

Application programming interfaces consist of two components:

• Technical specification describing the data exchange options between solutions with the specification done in the form of a request for processing and data delivery protocols
• Software interface written to the specification that represents it.

Due to these components APIs are sometimes thought of as contracts, with documentation that represents an agreement between parties.

The software that needs to access information or functionality from another software, calls its API while specifying the requirements of how data/functionality must be provided. The other software returns data/functionality requested by the former application.

And the interface by which these two applications communicate is what the API specifies.

Every API contains and is implemented by function calls — language statements that request software to perform particular actions and services. Function calls are phrases composed of nouns and verbs, for example:

• Start or finish a session
• Get amenities for a single room type

Function calls are described later on in the API documentation section.

APIs serve numerous purposes. Generally, they can simplify and speed up software development. Developers can add functionality from other providers to existing solutions or build new applications using services by third-party providers. In all these cases, specialists don’t have to deal with source code, trying to understand how the other solution works. They simply connect their software to another one. In other words, APIs serve as an abstraction layer between two systems, hiding the complexity and working details of the latter.

Specifications

Several efforts have been made to make API designs a little easier and their implementation more useful.
The goal of API specifications is to standardize data exchange between web services. However, standardization in this case means the ability of diverse systems, written in different programming languages and/or running on different OSs(operating systems), or using different technologies, to seamlessly communicate with each other.

“RPC requires a lot of REST and little SOAP unlike GraphQL”

This is a phrase I coined to help understand main API specifications and protocols, What does it truly mean?

RPC: Remote Procedure Call.
REST: Representational State Transfer.
SOAP: Service Object Access Protocol.
GraphQL: Graph Query Language.

Remote Procedure Call (RPC).

RPC is the earliest, simplest form of API interaction. It is about executing a block of code on another server, and when implemented in HTTP or AMQP it can become a Web API.

Representational State Transfer (REST).

REST is all about a client-server relationship, where server-side data are made available through representations of data in simple formats. This format is usually JSON or XML but could be anything.

Service Object Access Protocol (SOAP).

APIs designed with SOAP use XML for their message format and receive requests through HTTP or SMTP. SOAP makes it easier for apps running in different environments or written in different languages to share information.

Graph Query Language (GraphQL).

GraphQL is essentially RPC, with a lot of good ideas from the REST/HTTP community tacked in. It is one of the fastest growing API ecosystems out there. It is basically RPC with a default procedure providing a query language, a little like SQL — if that is something you are familiar with. You ask for specific resources and specific fields, and it will return that data in the response.

Documentation

The API documentation is a reference manual with all needed information about the API, including functions, classes, return types, and arguments.

A well-written and structured API documentation that explains how to effectively use and integrate an API in an easy-to-comprehend manner will make a developer happy and eager to recommend the API to peers.

Numerous content elements make good documentation, such as:

• A quick start guide
• Authentication information
• Explanations for every API call (request)
• Examples of every request and return with a response description, error messages, etc.
• Samples of code for popular programmatic languages like javascript, python, php e.t.c

In conclusion

APIs simplify how developers integrate new application components into an existing architecture, they help business and IT teams collaborate.