API Fundamentals

Client-Server
the client-server model is where the client (like a web browser or app) asks the server for something, like data or actions. The server processes the request and sends back what the client needs.

Stateless vs Stateful

• In a stateless API, each request from the client to the server must contain all the information needed to understand and process the request. The server does not retain any state or context between requests.
• In a stateful API, the server retains information about the client's state between requests. This means that the server can remember and use context from previous interactions. Ex: session-based authentication

REST vs RPC vs GraphQL

• REST are resource based identified by URLs and use standard HTTP method like (GET,POST,DELETE) to operate on resources
• RPC is a protocol that allows a client to execute procedures or functions on a remote server as if they were local calls.
• GraphQL is a data query and manipulation language for APIs, that allows a client to specify what data it needs.

API Versioning

url           : http://example.com/api/v1/users
query param   : http://example.com/api/users?version=1
header        : GET /api/users X-API-Version: 1
accept header : Accept: application/vnd.example.v1+json 

-

Semantic Versioning

MAJOR Version  : 1.0.0 to 2.0.0
MINOR Version  : 1.1.0 to 1.2.0
PATCH Version  : 1.1.1 to 1.1.2
Pre-release    : 1.0.0-alpha to 2.1.0-beta.1
Build metadata : 1.0.0+build5678

-

OpenAPI (swagger)

• OpenAPI is a specification for defining and documenting RESTful APIs.
• OpenAPI uses a standardized format (usually written in YAML or JSON) to describe APIs
• Tools : Swagger UI, Swagger codegen, OpenAPI generator

Metadata
API metadata is information about the API itself, not the data the API provides. It's like a map or guide that tells you how to use the API. Think of metadata as the labels, instructions, and rules you need to follow when using the API.

openapi: 3.0.0
info:
  title: Simple API
  description: A basic API for managing users.
  version: 1.0.0

paths:
  /users:
    get:
      summary: Get all users
      description: Retrieves a list of all users.
      responses:
        '200':
           description: A list of users
           content: application/json

-

Resource Identifier & Integrity check

• resource is assigned unique identifier like UUID. These identifiers often include checksums or other mechanisms to verify that the resource hasn't been altered or corrupted.
• When you download a file, it often includes checksum. After downloading, you can use this code to check if the file is the same as the original and hasn’t been changed or corrupted.

{
  "resource_id": "550e8400-e29b-41d4-a716-446655440000",
  "checksum": {
    "type": "SHA-256",
    "value": "772ch98fh7wcttcfc204d14e85b"
  }
}

-

Pagination

• Offset based pagination
  • GET /items?offset=20&limit=10
  • offset (starting point) and a limit (number of items per page)
• Cursor based pagination
  • GET /items?cursor=eyJhbGciOiJIUzI1NiIsInR5cCI6I
  • request fetches items starting from the position indicated by the cursor. Use the given cursor to fetch next item
• Page-Based Pagination
  • GET /items?page=2&limit=10
  • This request fetches items for the second page, with 10 items per page.
• Keyset-Based Pagination
  • GET /items?start_after=12345&limit=10
  • This request fetches items after the item with ID 12345.

Filtering

• query param
  • GET /items?category=electronics&price_min=100&price_max=500
  • use query param as filter when the filter criteria are optional
• path param
  • GET /items/category/electronics

• request body (for complex filter)
  

   {
     "category": "electronics",
     "price": {
        "min": 100,
        "max": 500
     }
   }
  

  -

Partial Updates & Partial Retrieve

• Partial update refers to modifying only specific fields or attributes of a resource without having to send the entire resource. PATCH method typically used for partial updates. It allows you to send only the fields you want to update.

• Partial retrieval refers to requesting only specific fields or attributes of a resource, rather than retrieving the entire resource.
  

  PATCH /users/123
  Content-Type: application/json
  
  {
    "email": "newemail@example.com"
  }
  
  GET /users/123?fields=name,email
  Content-Type: application/json
  
  {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
  

-

Field Mask

• Use field masking if you want to protect sensitive data like customer phone number or social security number for data privacy.
  

  {
    "name": "Jane Smith",
    "ssn": "XXX-XX-6789"
  }
  

  -

API Traffic Management

• Rate limiting: Restricts the number of API requests a client can make in a given period (e.g., per minute, hour, or day).
• Quota Management: Enforces limits on the amount of data or number of requests a client can consume over a longer period (e.g., monthly quotas).
• Throttling: Temporarily limits the rate at which requests are processed to prevent system overload or to manage traffic spikes.
• Load balancing: Distributes incoming API requests across multiple servers or instances to ensure even load distribution and improve reliability.
• Caching: Stores frequently accessed API responses temporarily to reduce latency and server load.

Serialization & Deserialization
Serialization refers to the process of converting data into a format that can be easily transmitted over a network or stored in a file.

Pre-Request Validation (validateOnly=true)
pre validate data to ensure data is valid before performing crititcal operation

POST /api/users?validateOnly=true HTTP/1.1
Host: example.com
Content-Type: application/json

{ 
  "username": "user1",
  "password": "pass123"
}

-

Long-Running Operations (LROs)

• Polling involves periodically checking the status of a long-running operation by sending repeated requests to the server.
• Waiting involves the client receiving a response immediately that indicates the operation is underway, with an estimate of when it will be completed. The client is informed to wait for completion without continuous polling.

• Pausing and Resuming allow clients to temporarily halt a long-running operation and later resume it from where it left off.
  

  POST /api/operations/{operationId}/pause 
  
  Response:
  {
     "status": "paused"
  }
  
  POST 
  /api/operations/{operationId}/resume
  
  Response:
  {
     "status": "resumed"
  }
  

  -

Retry Mechanisms

• Retry-After Header is used in HTTP responses to indicate how long the client should wait before retrying a failed request.
• Exponential Backoff is a strategy for retrying requests where the wait time between retries increases exponentially, e.g., 1s, 2s, 4s, 8s, etc.

API Batch Operation
Batch Operations is use for handling multiple requests or operations in a single API call. This approach can help improve efficiency, reduce network overhead, and simplify the management of multiple related operations.

POST /api/batch HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "operations": [
    { "method": "POST", "url": "/api/users", "body": { "name": "Alice" } },
    { "method": "PUT", "url": "/api/users/123", "body": { "name": "Bob" } },
    { "method": "DELETE", "url": "/api/users/456" }
  ]
}

Response:
[
  { "status": 201, "body": { "id": "123" } },
  { "status": 200, "body": { "name": "Bob" } },
  { "status": 204 }
]

-

API Purge & Soft Deletion

• Soft deletion marking a resource as deleted without actually removing it from the database. This allows the resource to be "deleted" in a logical sense but still retains it in the storage for potential recovery or auditing.
• Purge refers to the complete removal of a resource from the database. This approach deletes the resource permanently, with no way to restore it.

Digital Signature
digital signature is a cryptographic technique used to verify the authenticity and integrity of a digital message or document.

1. Set Up Key Pair
    - Generate an RSA key pair (private key and public key).
    - Save or securely store these keys for later use.

2. Sign the Data
    - Hash the Data: Create a hash of the message or document using a hashing algorithm (e.g., SHA-256).
    - Encrypt the Hash: Encrypt the hash with the private key to create the digital signature.
    - Attach Signature: Attach the digital signature to the original message or document.

3. Send the Data
    - Transmit the message along with the digital signature to the recipient.

4. Verify the Signature
    - Decrypt the Signature: Use the sender’s public key to decrypt the digital signature and obtain the original hash.
    - Hash the Received Data: Generate a new hash from the received message or document.
    - Compare Hashes: Compare the new hash with the decrypted hash. If they match, the message is verified.

-

Request Authentication

• Proof of Origin: Ensures the authenticity of the request sender.
• Integrity: Guarantees that the request data hasn't been tampered with.
• Prevention of Repudiation: Ensures the sender can't deny sending the request.
• OAuth: Provides a secure and standardized way for third-party apps to access user resources without sharing credentials.
• JWT: A token-based authentication method that securely transmits claims and verifies authenticity.