🚀 Application Programming Interfaces

A comprehensive guide to contracts that let different software systems exchange data reliably.

Production Ready Developer Friendly

Types of APIs

Web APIs

HTTP Exposed over the internet (REST, GraphQL).

  • Use cases: Mobile apps, 3rd-party integrations.
  • Pros: Ubiquitous, scalable.
  • Cons: Network latency.

Library APIs

Interfaces provided by SDKs or packages.

  • Use cases: Image processing, Math libraries.
  • Pros: Fast, Type-safe.
  • Cons: Version coupling.

OS APIs

System calls (files, network, UI).

  • Use cases: Desktop apps, Drivers.
  • Pros: High performance.
  • Cons: Platform specific.

Hardware APIs

Interfaces to physical devices (IoT).

  • Use cases: Sensors, Cameras.
  • Pros: Real-world integration.
  • Cons: Vendor quirks.

How APIs Work

APIs hide internal complexity and present a stable contract to consumers via a Request-Response flow.

  1. Client builds request: Method, URL, headers, body.
  2. Server processes: Validates, authorizes, executes logic.
  3. Server responds: Status code, headers, data.
// Request
GET /v1/weather?city=Hyderabad HTTP/1.1
Host: api.example.com
Accept: application/json

// Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "Hyderabad",
  "temp_c": 28.4,
  "condition": "Partly Cloudy"
}

⚖️ REST vs GraphQL

Aspect REST GraphQL
Contract Multiple endpoints, fixed resources Single endpoint, typed schema
Data Fetching Over/under-fetch possible Client specifies exact shape
Caching Simple (URL/Method based) Complex (Needs field-level strategies)
Versioning Path or Header (v1, v2) Evolve schema (deprecate fields)
Example Comparison
// REST
GET /v1/users/42
GET /v1/users/42/posts
// GraphQL
query { 
  user(id: 42) { 
    name 
    posts { title } 
  } 
}

Authentication

API Keys: Simple shared secret. Authorization: ApiKey <key>
OAuth 2.0: Delegated access tokens (Bearer). Authorization: Bearer <token>
HMAC: Request signing for integrity (Banking/Finance).

Status Codes

  • 200 OK Success
  • 201 Created Resource created
  • 400 Bad Request Invalid input
  • 401 Unauthorized Missing credentials
  • 403 Forbidden Insufficient scope
  • 500 Server Error Unexpected fault

✨ Best Practices

Design
  • Predictable naming
  • Plural resources
  • Cursor pagination
Security
  • TLS Everywhere
  • Least Privilege
  • Strict Validation
Reliability
  • Timeouts
  • Rate Limiting
  • Circuit Breakers
Docs
  • OpenAPI Schemas
  • Changelogs
  • Real examples

FAQ

API: The interface/contract.
SDK: A toolkit that wraps an API with convenience code and docs for a specific language.

Plan carefully: Version your API, deprecate old fields, document migrations, and provide overlap periods.