API - The Fundamentals

Having been involved in many API integration initiatives, I’d like to share some key concepts that can assist in effectively managing projects that involve API integrations.

Whether the project involves building microservices, fintech platforms, or enterprise integration layers, understanding key API design concepts is essential to create solutions that are secure, scalable, and maintainable.

An endpoint is a specific URL where an API can be accessed. It represents a resource or service exposed by the system.

Example:

GET https://api.bank.com/customers
GET https://api.bank.com/customers/123

• /customers retrieves a list of customers
• /customers/123 retrieves a specific customer

Well-designed endpoints should be clear, consistent, and resource-oriented.

HTTP methods define the type of action performed on a resource.

Common methods include:

Example:

POST /payments

This creates a new payment resource.

Most APIs follow a request-response communication pattern.

1. Client sends a request
2. Server processes the request
3. Server returns a response

Example:

Request

GET /accounts/456

Response

</> json
{
"accountId": "456",
"balance": 1500
}

This structured interaction ensures predictable communication between systems.

HTTP status codes communicate the result of an API request.

Common examples:

Correct status codes improve debugging and API usability.

4xx codes indicate issues with the client’s request
5xx codes indicate that the server, not the client, is responsible for the error.

Authentication verifies who is accessing the API.

Common authentication methods include:

• API Keys
• OAuth tokens
• JSON Web Tokens (JWT)
• Multi-factor authentication (MFA)

Authentication protects APIs from unauthorized access.

Authorization determines what actions the authenticated user is allowed to perform.

For example:

Authorization ensures least privilege access.

An access token is a temporary credential used to access protected APIs.

Example header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Characteristics:

• Short-lived
• Securely signed
• Revocable

Access tokens improve session security and API protection.

OAuth 2.0 is a widely adopted authorization framework that allows third-party applications to access user data securely.

Common OAuth flows include:

• Authorization Code Flow
• Client Credentials Flow
• PKCE Flow (mobile applications)
• Device Flow

OAuth enables secure delegated access without sharing passwords

Rate limiting controls how many requests a client can make within a time period.

Example:

100 requests per minute

Benefits include:

• Preventing abuse
• Protecting backend services
• Ensuring fair API usage

Throttling dynamically slows down request processing when traffic spikes.

Example:

• First 100 requests processed normally
• Additional requests delayed

Throttling helps maintain system stability during peak loads.

Pagination splits large datasets into smaller manageable pages.

Example:

GET /transactions?page=2&limit=50

Advantages:

• Faster responses
• Lower memory usage
• Better client performance

Caching stores API responses temporarily to reduce processing time and improve performance.

Common caching layers:

• Browser cache
• CDN
• API gateway
• Application cache

Example header:

Cache-Control: max-age=3600

Caching improves scalability and response speed.

Webhooks enable event-driven communication between systems.

Instead of continuously polling an API, the server sends updates automatically.

Example event notification:

POST /webhook/payment-success

Common webhook use cases include:

• Payment notifications
• CI/CD pipelines
• Order processing

APIs evolve over time, and versioning ensures backward compatibility.

Example approaches:

URL versioning:

/v1/accounts
/v2/accounts

Header versioning:

Accept: application/vnd.api.v2

Versioning prevents breaking existing integrations.

The OpenAPI Specification (OAS) provides a standard way to document APIs.

It defines:

• Endpoints
• Request parameters
• Response formats
• Authentication methods

OpenAPI enables tools to automatically generate:

• API documentation
• Client SDKs
• Test frameworks

An API Gateway acts as the central entry point for APIs.

Key responsibilities include:

• Authentication
• Rate limiting
• Traffic routing
• Security enforcement
• Monitoring and logging

API gateways are critical in microservices and cloud-native architectures.

Microservices architecture breaks applications into independent services that communicate through APIs.

Example services:

• Customer Service
• Payment Service
• Notification Service

Benefits include:

• Independent deployment
• Better scalability
• Fault isolation

APIs are the communication backbone of microservices.

Good APIs provide structured and meaningful error responses.

Example:

</> json
{
"error": "INVALID_ACCOUNT",
"message": "Account does not exist"
}

Best practices include:

• Consistent error format
• Clear error messages
• Proper HTTP status codes

This helps developers quickly troubleshoot integration issues.

Data mapping is the process of transforming data from one system’s format into another system’s expected format.

This is especially important in system integrations and API mediation layers.

Example:

### Internal System Response
</> json
{
"cust_id": "C1001",
"cust_name": "John Tan"
}

### API Response
</> json
"customerId": "C1001",
"customerName": "John Tan"
}

Mapping may include:

• Field renaming
• Data transformation
• Format conversion
• Aggregating multiple sources

Data mapping is often implemented in:

• API gateways
• Integration middleware
• Microservices

Proper mapping ensures data consistency and interoperability between systems.

As organizations continue adopting cloud-native architectures, microservices, and event-driven systems, well-designed APIs will be a critical foundation of modern software platforms.