It is a set of rules and protocols that allows different software applications to communicate and interact with each other; an intermediary enabling one software component to request services or data from another.
The communication between a client and a server via an API follows a standard request-and-response cycle, typically over the internet using HTTP protocols.
Request from the Client: A client application, such as a mobile app, web browser, or server, initiates a request. This request contains several key components:
Endpoint: A specific URL that identifies the resource the client needs.
Method: An HTTP method (e.g., GET, POST, PUT, DELETE) that defines the action the client wants to perform on the resource.
Headers: Metadata providing extra details about the request, such as the authentication token.
Body: The data needed to perform the action, such as the content for a new blog post.
Request Processed by the API: The request is sent to the API, which serves as a gateway to the server. The API first performs several checks, including:
Authentication and Authorisation: It verifies the identity of the client and ensures they have the necessary permissions.
Input Validation: It confirms the request data is properly formatted and valid.
Server Processes the Request: The API forwards the validated request to the server, which performs the necessary actions, such as retrieving data from a database or updating a record.
Response from the Server: The server sends a response back to the API. The response includes:
Status Code: A three-digit code indicating the outcome (e.g., 200 OK for success, 404 Not Found for an error).
Response Headers: Additional information about the server's response.
Response Body: The requested data, typically in a standardised format like JSON or XML.
API Delivers the Response: The API transfers the response to the initial client application, which then processes the data and presents it to the user in the appropriate format.
APIs are categorised based on their intended (1) Audience, (2) Architectural Style, and (3) Purpose/Function.
Public APIs: Also known as Open or External APIs, these are publicly available to any third-party developer with few or no restrictions. They are used to allow anyone to integrate a service's functionality into their own applications, such as a weather app using a public weather API.
Private APIs: Also called Internal APIs, these are restricted to use within a single organization. They are used to connect different internal systems and share proprietary data between various teams or departments.
Partner APIs: These APIs are shared only with specific, authorised business partners. Access is tightly controlled with authentication and licensing to facilitate secure business-to-business integrations.
Representational State Transfer (REST) APIs:
The most common architectural style for web APIs, REST, uses standard HTTP methods (GET, POST, PUT, and DELETE) to perform operations on resources.
RESTful APIs are popular for their simplicity, scalability, and flexibility.
Usually formatted as JSON and thus cross-platform.
Rest is stateless - each request is completely independent, allowing servers to handle millions of requests without having to keep track of each request.
Example: Restuarant - Customer/Client requests food via the waiter (API), who goes and retrieves it from the Kitchen/Server.
Simple Object Access Protocol (SOAP) APIs:
SOAP is a messaging protocol with a strict, XML-based message format; every request & response must follow strict rules (Envelope, Header - Metadata, Body - Request/Response).
Though older and more rigid than REST, it is valued in enterprise environments that require high security and reliability, such as in finance and telecommunications.
SOAP is protocol independent, but is commonly used over HTTPS, but can run over SMTP, TCP, HTTP, etc.
SOAP includes built-in standards for error handling, security, and transaction support; thus, it is used in industries where reliability and precision are critical.
Graph Query Language (GraphQL) APIs:
This query language for APIs allows clients to request exactly the data they need, nothing more and nothing less.
It provides a single endpoint for all requests and is useful for complex applications that need to retrieve data from multiple sources efficiently.
Real-time subscriptions - allow apps to listen for live updates automatically.
GraphQL includes a built-in playground, allowing developers to test queries instantly.
Remote Procedure Call (RPC) APIs:
RPC APIs allow a client to execute functions or procedures on a remote server as if they were running locally.
There are several implementations, including XML-RPC, JSON-RPC, and the higher-performance gRPC.
RPC is slower, text-heavy, and does not scale well, especially for real-time apps.
gRPC API: (https://grpc.io/docs/what-is-grpc/introduction/)
It is an open-source Remote Procedure Call (RPC) framework developed by Google.
It enables client and server applications to communicate efficiently and transparently, regardless of their programming language or environment.
gRPC was built for speed, performance, and precision.
Instead of using text-based JSON over HTTP, gRPC uses protocol buffers (protobuf) that compress data into a compact binary format that is lightning fast to process.
gRPC takes advantage of HTTP2, allowing multiple requests to run over a single connection.
gRPC supports 4 communication patterns:
Simple Request-Response
Server Streaming for live updates
Client streaming for sending continuous data
Bi-directional streaming (both sides simultaneously chat in real time).
WebHook APIs:
Often referred to as a "reverse API," is a method for one application to provide real-time, event-driven notifications to another application.
Instead of a client requesting updates from a server, when a specific event occurs in the source application, it automatically sends an HTTP POST request (One-Way Communication) containing relevant data to a pre-configured URL (the "callback URL") in the receiving application.
Webhooks are generally simpler to implement than WebSockets, as they leverage standard HTTP requests.
Use Cases: Integrating with third-party services (e.g., payment gateways, CRM systems), triggering automated workflows (e.g., sending an email after a new user signs up), receiving notifications from SaaS applications.
WebSockets APIs:
Unlike the request-response model of most web APIs, WebSocket APIs enable continuous, bidirectional communication between a client and server.
The persistent connection minimizes overhead and latency, making them ideal for applications requiring continuous, real-time data exchange.
WebSockets maintain the state of the connection, meaning both ends are aware of the communication's ongoing status.
This makes them ideal for real-time applications like live chat, games, or stock tickers.
A WebSocket connection starts with a handshake over an active TCP connection; a client sends an HTTP/HTTPS GET request to a server to upgrade the connection to a WebSocket connection, and if the handshake completes successfully, the client and server can communicate using the WebSocket protocol. No requests or responses are needed.
WebSockets allow the server to push data to clients (unlike in traditional APIs where the client always request for data).
WebSocket allows for the transfer of plain text, JSON, or binary files (images or videos).
Web Real-Time Communication (WebRTC) API:
It is a set of standardised JavaScript APIs that enable web browsers and mobile applications to engage in real-time communication (RTC) directly between peers (without servers), without requiring plugins or downloads.
This facilitates functionalities like audio and video calling, video conferencing, live streaming, and peer-to-peer data transfer directly within web applications.
Composite APIs: These APIs bundle multiple API requests into a single call, executing them in a defined sequence. They are often used in microservices architectures to reduce the number of requests and improve performance.
Data/Database APIs: These are used to connect applications to database management systems. They provide a controlled and secure way for an application to access and manipulate data stored in a database