What is API? Concise explanation in simple words (2023)

The topic of API is very interesting and large, so I’ve divided the material into three parts, each of which is designed for a different audience. If you’re just starting to understand the subject, read everything in order. And if you know something already, choose the part that interests you.

Part 1 - A Simple Explanation of the API (this article)

1. What is API
2. How API works
3. Protocols of API

Part 2 - How to write your API (working on an article)

1. The best frameworks for API
2. How to make your own API - FastAPI
3. How to write documentation for API

Part 3 - How to make money with API (working on the article)

1. How to earn with API
2. Useful API links
3. API courses

So, let’s go…

What is API

API stands for Application Programming Interface. In the article below I just use “API”.

Professionals define API as a service contract between two applications. That is, like any normal contract, which specifies how applications (programs, services) should interact with each other, how they should formulate their requests and what to expect as responses. By the way, good developers always describe all this in the API documentation.

In addition to normal documentation, here are other important characteristics of a good API:

• Easy to understand how it works
• Easy to use, even without documentation
• Hard to use it incorrectly (foolproof)
• Easy to read and maintain code that uses the API
• Powerful enough to meet requirements
• Easy to scale and add functionality
• Meets user expectations

How do APIs work?

APIs are usually explained as a client-server interaction. The application that sends the request is called the client and the application that sends the response is called the server. The API provides communication between services via request-response loops. The loops may or may not require an Internet connection.

Applications exchange these requests, responses, and data by following special rules that govern the use and application of such calls, define the commands and data types accepted, and set certain standards for API use. A set of such rules is called a protocol.

API Protocols

In the early 2000s, there were only two actual API protocols that most developers should have known about: SOAP and REST. In recent years, however, many new protocols have appeared, such as new implementations of RPC, GraphQL, Thrift, and others. A bit more about some of them below.

SOAP

SOAP (Simple Object Access Protocol) uses XML files to transfer data between web services. XML files are transferred over HTTP/HTTPS. SOAP also provides some flexibility by allowing data to be transferred over other protocols, such as Transmission Control Protocol (TCP), Simple Mail Transport Protocol (SMTP), User Data Protocol (UDP), etc.

Although SOAP is still the most widespread and stable, its popularity has recently been inferior to the newer protocols.

RPC

RPC (Remote Procedure Call) is a whole group of ways to describe how different computers can communicate with each other. Such a system has been around since the 1970s. In short, the client executes a function (or procedure) on the server and the server sends the result back to the client. Technically, the SOAP protocol is an example of RPC.

The following implementations of the RPC protocol are currently in use:

• JSON-RPC, created in the mid-2000s, makes extensive use of the JSON format, but supports only a small set of commands, and does not offer the flexibility that other protocols do. However, if you have a simple API use case, this protocol might be an okay solution.
• XML-RPC differs from JSON-RPC only in that the data is transferred as XML files. The built-in XML vocabulary is used to create queries and responses. The client defines the procedure and parameters in the request, and the server sends a response that may contain data or an error description.
• gRPC protocol is even newer, it was published by Google in 2015, and also uses HTTP as the transport layer. It uses the ProtoBuff format to transfer data. Unlike other protocols, gRPC allows developers to define the function calls they want, rather than choosing from predefined options (like GET and PUT in the case of REST).

REST

REST (Representational State Transfer) is one of the most popular nowadays. Though it should be made clear right away that REST is not a protocol, meaning it has no clear and generally accepted rules. REST is just an approach or, in other words, a set of recommendations to the developer about how to best organize the interaction of his application components on the network. That’s why you’ll find all sorts of different ways to implement these recommendations, what methods to use, what code to return, etc., depending on the situation.

The main features of the REST API are that each client request (REST request) to the server already contains all the information about what the client wants in the response (the desired representative state) from the server, and that the server doesn’t have to save client data (client session information) between different requests.

Client requests to the server are similar to the URLs you enter in a browser to open a Web site. The response from the server is simple data with no graphical display of the web page.

You may have also come across the term RESTful. It usually describes web services built with REST recommendations in mind. There are a total of six obligatory requirements (restrictions) for building distributed REST applications:

1. Client-server model. The application must use the client-server architecture. Separating the needs of the client from the needs of the server with the data increases the portability of the code and scalability of the entire application.
2. No State. No client state information is stored on the server between client requests. All requests must be designed so that the server receives all the information it needs to execute the request.
3. Caching. Clients can cache server responses. Server responses, in turn, must be explicitly or implicitly marked as cacheable or non-cacheable to prevent clients from receiving outdated or incorrect data.
4. Interface Unification. Applying commonality to the component interface simplifies the system architecture and improves the transparency of component interactions. But it can reduce efficiency because information is transmitted only in a standard form.
5. Multilayer System. The use of intermediate servers (“layers” in the hierarchical network structure) can improve scalability due to load balancing and distributed caching.
6. Code on Demand. REST allows you to extend the functionality of the client by downloading and executing code in the form of an applet or script. This simplifies the client because you can reduce the number of functions that need to be implemented in advance.

The advantages of REST include reliability, performance (due to the cache), scalability, ease of use, support and adaptation to new requirements as they arise.

GRAPHQL

GraphQL (Graph Query Language) was developed at Facebook and released in 2015. It is an attempt to overcome some of the limitations and imperfections of REST.

The main advantage of GraphQL is that the client itself determines the desired data and format in its request, and GraphQL returns the data in the same format. This saves time and memory because the server’s response is only the bare minimum - only the data that is needed, rather than ready-made files with a lot of information that needs to be further processed.

It also reduces the number of HTTP requests themselves because GraphQL allows you to query multiple databases, microservices, and other APIs with a single GraphQL endpoint.

APACHE THRIFT

Apache Thrift, like GraphQL, was created at Facebook. It was developed with a focus on two main goals: enabling interoperability with services written in different languages, and scalability.

Essentially, it’s an implementation of RPC that uses a code generation mechanism combined with a software stack to create an API. The stack helps in writing code for the client and server side. The code syntax is flexible and intuitive. A special mechanism generates code in any programming language the developer chooses.

The main advantage of Thrift is the ease with which it allows you to change the protocol used by a service once the service is defined. Combined with the fact that Thrift also supports many different transport methods and several different server process implementations, this means that Thrift is well-suited for situations where you will need to change or update your architecture and API implementation frequently.

On the other hand, the flexibility that Thrift provides in choosing how to implement the API can lead to less organization and consistency than with other API protocols that offer only one way of doing things.

Where APIs are used

APIs are ubiquitous in how applications interact with each other and with various online services. So ubiquitous that if you turn off all APIs at once, almost all services on the Internet and most of the applications you are used to will simply stop working.

With an API, programmers can take advantage of third-party applications without having to write and maintain their own code for the task. For example, if your application is supposed to show the weather, it’s easier to use the publicly available weather API to provide that information to your users than to write your own weather code from scratch.

Other examples of such services are user registration API, payment system services, social networks and many others. I’ll talk more about this in Part 3.

Now that we understand what an API is and how it all works, let’s look at the tools you can use to write your API quickly and efficiently.

Part 2 - How to write your API - coming soon!

Part 3 - How to make money with APIs - still working on the article.

😎