API - REST, GraphQL, WebSocket, Webhook, RPC/gRPC, SOAP

date

Jul 15, 2024

slug

what-is-api

status

Published

What is an API?

An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface, offering a service to other pieces of software.

The term API may refer either to the specification - an architecture blueprint that describes the interface behavior and serves as a rough guide on how to build a particular API, or to the implementation - a set of programming code that enables data transmission between one software product and another.

How do APIs work?

APIs let your product or service communicate with other products and services without having to know how they’re implemented. They simplify how developers integrate new application components into an existing architecture.

The working principle of an API is commonly expressed through the request-response communication between a client and a server. An API works as a middle layer between the client and the server, making it possible to send data requests and responses.

API components: calls, keys, endpoints

An API call is a request a client app forwards to a server. It contains

operations to be executed (e.g. GET to retrieve a resource or POST to send data),

authentication details (e.g. an API key that identifies the client),

additional parameters, and

a destination address - the URL of the API endpoint

An API endpoint is like an entrance to a place where a sought-after resource (data or feature) lives. The endpoint checks the API key and, if approved, sends back a response with the information on the operation status (error or success) and requested resources.

APIs vs webhooks

A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between 2 APIs. It enables one-way communication between apps.

Webhooks are often referred to as reverse APIs or push APIs, because they put the responsibility of communication on the server, rather than the client. Instead of the client sending HTTP request, asking for data util the server responds, the server sends the client a single HTTP POST request as soon as the data is available.

Despite their nicknames, webhooks are not APIs; they work together. An application must have an API to use a webhook.

Webhooks work best for sending automated reminders, notifications, and real-time updates. However, compared to full-fledged APIs, their lightweight relatives lack functionality, cannot handle intense and complex two-way communication, and have fewer security capabilities.

API vs SDK

While APIs let you connect your app with existing data sources and services, a software development kit (SDK) is a suite of platform-specific tools (libraries, compilers, debuggers, code samples, etc.) and documentation that lets developers build an application faster and in a standardized way.

Often, the SDK contains an API or a set of APIs. Conversely, you can build an API using the SDK.

For example, for those who want to have dynamic maps in their apps, Google provides Maps SDKs for web, iOS, Android, and cross-platform (Flutter) development.

API types

APIs can be categorized based on the ways they are available for use and according to their initial design purposes.

APIs by availability, aka release policies

Private APIs

Even if apps are publicly accessible, the interface itself remains available only for those working directly with the API publisher. The private strategy allows a company to fully control API usage.

Partner APIs

This type of API is openly promoted but shared with business partners who have signed an agreement with the publisher. The common use case for partner APIs is software integration between two parties.

Public APIs

Also known as developer-facing or external APIs, these APIs are available for any third-party developers.

There are two types of public APIs – open (free of charge) and commercial ones.

Open public APIs

All features are public and available for use without restrictive terms and conditions. The API description and any related documentation must be openly available.

Commercial API

Users pay subscription fees or utilize APIs on a pay-as-you-go basis.

APIs by use cases

APIs can be classified according to the systems for which they are designed.

Database APIs

Enable communication between an application and a database management system. Developers work with databases by writing queries to access data, change tables, etc.

Operating systems APIs

Define how applications use the resources and services of operating systems.

Remote APIs

Remote APIs are designed to interact through a communications network.

By remote, we mean that the resources being manipulated by the API are somewhere outside the computer making the request. Two remotely located applications are connected over a communications network.

Because the most widely used communications network is the internet, most remote APIs are designed based on web standards. Not all remote APIs are web APIs, but it’s fair to assume that web APIs are remote.

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). These response messages usually take the form of an XML or JSON file.

Developers can use web APIs to extend the functionality of their apps or sites.

Most businesses use more than one API to connect applications and share information. Some end up needing an API management tool to help them control, distribute, and analyze different APIs.

API formats and specifications

A document or standard that describes how to build or use such a connection or interface is called an API specification. API specifications aim to standardize data exchange between web services. A computer system that meets this standard is said to implement or expose an API.

In this case, standardization means the ability of diverse systems written in different programming languages, running on different OSs, or using different technologies to seamlessly communicate with each other.

Specifications differ across API formats. The following are the most common ones.

Remote Procedure Call (RPC)

Remote Procedure Call (RPC) is a protocol that allows a client application to call a remote server's method or function as if it were a local function call.

This protocol specifies the interaction between applications based on the client-server architecture. One program (client) requests data or functionality from another program (server) located in another computer on a network, and the server sends the required response.

Stub libraries are generally installed on the client and server. Client stubs convert parameters used in function calls and reconvert the result obtained from the server after function execution. Server stubs, on the other hand, reconvert parameters passed by clients and convert results back after function execution.

A procedure call is also sometimes known as a function call or a subroutine call. RPC and SOAP are two methods for implementing remote procedure calls between distributed systems.

Simple Object Access Protocol (SOAP)

SOAP is a messaging protocol that encodes messages in XML and transports them through HTTP or HTTPS. SOAP makes it easier for apps running in different environment or written in different languages to share information.

Generally speaking, this specification contains the syntax rules for request and response messages sent by web applications. APIs that comply with the principles of SOAP enable XML messaging between systems through HTTP or Simple Transfer Protocol (SMTP) for transferring mail.

SOAP is mostly used with enterprise web-based software to ensure the high security of transmitted data. SOAP APIs are preferred among providers of payment gateways, identity management, and CRM solutions, as well as financial and telecommunication services. It’s also frequently used for legacy system support.

Representational State Transfer (REST)

REST is a software architectural style with 6 constraints for building applications that work over HTTP, often web services.

Web APIs that adhere to the REST architectural constraints are called RESTful APIs. These APIs use HTTP requests (AKA methods or verbs) to work with resources: GET, PUT, HEAD, POST, PATCH, CONNECT, TRACE, OPTIONS, and DELETE.

REST differs from SOAP in a fundamental way: SOAP is a protocol, whereas REST is an architectural style. This means that there’s no official standard for RESTful web APIs.

APIs are RESTful as long as they comply with the 6 guiding constraints of a RESTful system:

Uniform Interface

This constraint is core to the design of RESTful APIs. It suggests that there should be an uniform way of interacting with a given server irrespective of device or type of application (website, mobile app).

It includes 4 facets:

Resource-Based: Individual resources are identified in requests. For example: API/users.
Manipulation of Resources Through Representations: Client has representation of resource and it contains enough information to modify or delete the resource on the server, provided it has permission to do so. Example: Usually user get a user id when user request for a list of users and then use that id to delete or modify that particular user.
Self-descriptive Messages: Each message returned to a client contains enough information to describe how the client should process the message so that server can easily analyses the request.
Hypermedia as the Engine of Application State (HATEOAS): It need to include links for each response so that client can discover other resources easily.

Client-Server Architecture

REST architecture is composed of clients, servers, and resources, and it handles requests through HTTP.

Stateless

No client content is stored on the server between requests. Information about the session state is, instead, held with the client. Statelessness enables greater availability since the server does not have to maintain, update or communicate that session state. There is a drawback when the client need to send too much data to the server so it reduces the scope of network optimization and requires more bandwidth.

Cacheable

Every response should include whether the response is cacheable or not and for how much duration responses can be cached at the client side. Client will return the data from its cache for any subsequent request and there would be no need to send the request again to the server. But sometime there are chances that user may receive stale data.

Layered system

Client-server interactions can be mediated by additional layers. Each layer doesn’t know any thing about any layer other than that of immediate layer and there can be lot of intermediate servers between client and the end server. These layers could offer additional features like load balancing, shared caches, or security.

Code on demand (optional)

Servers can extend the functionality of a client by transferring executable code. The examples of code on demand may include the compiled components such as Java Servlets and Server-Side Scripts such as JavaScript.

Rules of REST API

There are certain rules which should be kept in mind while creating REST API endpoints.

REST is based on the resource or noun instead of action or verb based. It means that a URI of a REST API should always end with a noun. Example: /api/users is a good example, but /api?type=users is a bad example of creating a REST API.

HTTP verbs are used to identify the action.

A web application should be organized into resources like users and then uses HTTP verbs to modify those resources. And as a developer it should be clear that what needs to be done just by looking at the endpoint and HTTP method used.

Always use plurals in URL to keep an API URI consistent throughout the application.

Send a proper HTTP code to indicate a success or error status.

REST is considered a simpler alternative to SOAP, which many developers find difficult to use because it requires writing a lot of code to complete every task and following the XML structure for every message sent. REST sticks to another logic since it makes data available as resources. Each resources is represented by a unique URL, and one can request this resource by providing its URL.

RESTful systems support messaging in different formats, such as plain text, HTML, YAML, XML, and JSON, while SOAP only allows XML.

In recent years, the OpenAPI specification has emerged as a common standard for defining REST APIs. OpenAPI established a language-agnostic way for developers to build REST API interfaces so that users can understand them with minimal guesswork.

gRPC

gRPC (Google RPC) is a cross-platform open-source RPC framework initially created by Google. The framework relies on HTTP/2 (supports TLS) and beyond performance, interoperability, and code generation offers streaming features and channels.

Like SOAP and REST, the transport layer for gRPC is HTTP. However, similar to RPC, gRPC allows developers to define any kind of function calls, rather than selecting from preset options such as PUT and GET in the case of REST.

By default, gRPC uses Protocol Buffers instead of JSON or XML as the Interface Definition Language (IDL) for serializing structured data. The developer needs to first define the structure of the data they want to serialize. Once the data structures have been specified, they use the protocol buffer compiler to generate the data access classes in the programming language of your choice. The data is then compressed and serialized in binary format at runtime.

gRPC is mostly used for communication between microservices because it is available in multiple languages and has a high performance.

GraphQL

GraphQL is a query language for APIs. It allows the client to detail the exact data it needs and simplifies data aggregation from multiple sources, so the developer can use one API call to request all needed data. Another special feature of GraphQL is that it uses a type system to describe data.

GraphQL lets developers construct requests that pull data from multiple data sources in a single API call.

WebSocket

WebSocket is a protocol allowing two-way communication over TCP. To initiate a connection, WebSocket needs HTTP support.

WebSockets provide a full-duplex communication channel over a single, long-lived connection, allowing real-time data exchange between a client and a server. This makes it ideal for interactive and high-performance web applications.

API documentation and API requirements

While the API specification mentioned above dictates how to build an API, API documentation explains how to effectively use and integrate it.

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;

tutorials; and

SDK examples (if SDKs are available) illustrating how to access the resource, etc.

Generation is the process of documenting APIs by developers. The specialists may use API documentation solutions (i.e., Swagger tools, Postman, Slate, or ReDoc) to unify documentation structure and design.

Why to use an API?

Generally, they simplify and speed up software development. Engineers can set access to data or expand their apps with functionality from third-party providers. But there are other reasons why you should consider APIs as a vital part of your business growth strategy.

Connecting internal systems. APIs allow you to integrate systems inside your business environment. It helps avoid data silos and facilitates information exchange between different departments.

Enhancing security. Many security flows become available due to APIs. Say, the single-sign-on (SSO) process, when a user can log in once to reach multiple services, is handled by a third-party Identity as a service Provider (IdaaS).