API documentation
1 What is an API?
An API, which stands for application programming interface, is a set of protocols that enable
different software components to communicate and transfer data. Developers use APIs to bridge
the gaps between small, discrete chunks of code in order to create applications that are powerful,
resilient, secure, and able to meet user needs. Even though you can't see them, APIs are
everywhere—working continuously in the background to power the digital experiences that are
essential to our modern lives.
2 Different types of APIs
2.1 REST (Representational State Transfer):
Uses the HTTP protocol.
Exchanges data typically in JSON format.
Based on a client–server architecture.
Platform-independent and works with various types of applications.
Stateless: each request is processed independently by the server.
2.2 SOAP (Simple Object Access Protocol):
A formal protocol for APIs.
Known for high security.
Uses protocols such as HTTP and SMTP for communication.
2.3 RPC (Remote Procedure Call):
Allows execution of functions or procedures on a remote server.
Simple but can be slower due to network overhead.
2.4 gRPC (Google Remote Procedure Call):
High-speed and high-performance API framework.
Uses Protocol Buffers (protobuf) for data serialization in a compact binary format.
Works over HTTP/2, allowing multiple requests over a single connection.
Supports unary requests (like REST), as well as server streaming, client streaming,
and bidirectional streaming.
Typically, 5–10 times faster than REST.
2.5 GraphQL:
A query language for APIs.
Allows clients to request only the exact data they need—no more, no less.
Uses a single endpoint for flexible queries.
Supports real-time updates.
2.6 Webhooks:
A reverse API mechanism used for sending automatic notifications.
Widely used in real-time web development to notify systems of events.
2.7 WebSocket:
Creates a persistent bi-directional communication channel between client and server.
Supports JSON, text and binary data formats.
2.8 WebRTC (Web Real-Time Communication):
Enables direct peer-to-peer communication between clients.
Supports audio, video, and data transfer without needing a server as an intermediary.
3 How to explore an API?
Exploring an API means learning how it works, testing its endpoints, and retrieving data. Here’s
a brief overview using the Spotify API as an example.
3.1 Explore Online
Visit the Spotify for Developers website.
Use the Spotify API Console to test requests directly in the browser.
Example: Get Beyoncé’s artist data using her ID: 6vWDO969PvNqNYHIOW5v0m.
You can also discover other APIs on websites like ProgrammableWeb or API List.
3.2 Use the Terminal with cURL
Install cURL on your system.
Send API requests from the command line.
Example:
curl -X GET [Link] -H
"Authorization: Bearer <YOUR_ACCESS_TOKEN>"
3.3 Use API Tools
Tools like Postman, Thunder Client (VS Code), or RestFox make API testing easier.
You can add headers, tokens (like the Spotify Bearer Token), and view JSON
responses.
3.4 Use Helper Libraries (Coding Approach)
Instead of using cURL or Postman, we can interact with APIs directly in code using helper
libraries. For example, Twilio provides a Java SDK to send WhatsApp messages via API.
3.4.1 Step 1: Set up the environment
Install Java (JDK)
Use an IDE like IntelliJ IDEA or VS Code
Create a Java project and add the Twilio library:
<dependency>
<groupId>[Link]</groupId>
<artifactId>twilio</artifactId>
<version>10.4.1</version>
</dependency>
3.4.2 Step 2: Write Java code to call the API
import [Link];
import [Link];
import [Link];
public class WhatsAppSender {
public static final String ACCOUNT_SID = " AC88072f37ec48798e080bd776d147534e";
public static final String AUTH_TOKEN = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
public static void main(String[] args) {
[Link](ACCOUNT_SID, AUTH_TOKEN);
Message message = [Link](
new PhoneNumber("whatsapp:+2126XXXXXXX"),
new PhoneNumber("whatsapp:+18143262752"),
"Hello from Java with Twilio WhatsApp API!"
).create();
[Link]("Message sent! SID: " + [Link]());
4 API authentication
4.1 Basic Auth
The simplest HTTP auth scheme:
Combines username & password,
Encodes them with Base64,
Sends them in the Authorization header with every request.
Example format: Authorization: Basic <base64(username:password)>
4.2 Bearer token
A bearer token is a string that gives access to protected resources. It acts as a transport
mechanism and can carry any token type:
Client sends credentials to server,
Server validates credentials,
Server generates random token,
Server saves token to database,
Server returns token to client,
Client sends bearer token in every request,
Server validates token on each request.
Note: Since the server must check the token in the database for every request, having multiple
API servers requires a centralized database, which increases infrastructure complexity.
4.3 Json Web Token
A JWT is a self-contained token consisting of three parts separated by dots
([Link]).
The header: Contains the signing algorithm and token type,
The payload: Contains claims about the user (e.g., user ID, roles). This data is Base64-
encoded, not encrypted,
The signature: Ensures the token is authentic. It is generated by combining the header and
payload, then hashing them using a secret key.
Note:
The server verifies the token by checking the signature mathematically using the secret
key.
No database lookup is required, making it 5–10 times faster than bearer tokens stored in a
database.
5 How to secure an API?
5.1 Rate limiting
Limit requests per IP/user/endpoint. Protects against abuse and mitigates DDoS.
5.2 CORS
Validate and sanitize inputs, use parameterized queries or prepared statements, and prefer ORM
libraries that avoid string concatenation for queries.
5.3 SQL & NoSQL injection
Validate and sanitize inputs, use parameterized queries or prepared statements, and prefer ORM
libraries that avoid string concatenation for queries.
5.4 Firewalls
Use network firewalls and a Web Application Firewall to block known attack patterns, filter
malicious requests, and protect exposed endpoints
5.5 CSRF
Add a secret code to every form or important request, and protect cookies so they only work on
your website and only over a secure (HTTPS) connection.
5.6 XSS
Escape or sanitize all user-controlled output, enforce a strict Content Security Policy (CSP), and
validate inputs to prevent script injection.
6 Good practices
6.1 HTTPS
Always use HTTPS, no exceptions, it use TLS encryption.
6.2 Set appropriate expiration times
Access Token: 15-60min.
Refresh Token: 7-30days.
Note: Stolen token = limited damage window.
6.3 Never roll your own crypto
Always use trusted, well-tested libraries instead of writing your own encryption or token logic.
Examples:
[Link]: jsonwebtoken.
Python: PyJWT.
Java: jjwt.
.NET: IdentityModel.
7 Resources:
[Link]
[Link]
[Link]
[Link]