API Fundamentals

curl -s \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.example.com/v1/items?limit=25

{
  "data": [...],
  "meta": {
    "count": 25,
    "next_cursor": "eyJvZmZzZXQiOjI1fQ"
  }
}

┌─────────────┐           ┌──────────────┐           ┌─────────────┐
│   Client    │           │  API Gateway │           │  API Server │
│             │           │              │           │             │
│  + Token    │─────────▶│  Validates   │─────────▶ │  Processes  │
│             │           │    Token     │           │   Request   │
└─────────────┘           └──────────────┘           └─────────────┘
     ↑                           │
     │                           │
     └───────────────────────────┘
          Returns Response

# Using curl
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     https://api.example.com/v1/items

HTTP Method    Endpoint              Action
───────────────────────────────────────────────────────
GET            /items                List all items
POST           /items                Create new item
GET            /items/\{id\}           Get single item
PATCH          /items/\{id\}           Update item
DELETE         /items/\{id\}           Delete item

curl -X GET "https://api.example.com/v1/items?limit=10&sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

{
  "data": [
    {
      "id": "it_123",
      "name": "Alpha Product",
      "status": "active",
      "created_at": "2024-12-01T10:30:00Z",
      "updated_at": "2024-12-15T14:22:00Z"
    },
    {
      "id": "it_124",
      "name": "Beta Service",
      "status": "active",
      "created_at": "2024-12-05T08:15:00Z",
      "updated_at": "2024-12-10T16:45:00Z"
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "eyJvZmZzZXQiOjEwfQ"
  }
}

curl -X POST "https://api.example.com/v1/items" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Product Launch",
    "description": "Q1 2025 flagship product",
    "status": "draft",
    "metadata": {
      "category": "electronics",
      "priority": "high"
    }
  }'

{
  "data": {
    "id": "it_125",
    "name": "New Product Launch",
    "description": "Q1 2025 flagship product",
    "status": "draft",
    "metadata": {
      "category": "electronics",
      "priority": "high"
    },
    "created_at": "2024-12-17T09:00:00Z",
    "updated_at": "2024-12-17T09:00:00Z"
  }
}

curl -X GET "https://api.example.com/v1/items/it_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

{
  "data": {
    "id": "it_123",
    "name": "Alpha Product",
    "description": "Premium product line",
    "status": "active",
    "metadata": {
      "category": "electronics",
      "sku": "APH-001"
    },
    "created_at": "2024-12-01T10:30:00Z",
    "updated_at": "2024-12-15T14:22:00Z"
  }
}

curl -X PATCH "https://api.example.com/v1/items/it_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "metadata": {
      "featured": true
    }
  }'

{
  "data": {
    "id": "it_123",
    "name": "Alpha Product",
    "description": "Premium product line",
    "status": "active",
    "metadata": {
      "category": "electronics",
      "sku": "APH-001",
      "featured": true
    },
    "created_at": "2024-12-01T10:30:00Z",
    "updated_at": "2024-12-17T09:15:00Z"
  }
}

curl -X DELETE "https://api.example.com/v1/items/it_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

{
  "data": {
    "id": "it_123",
    "deleted": true,
    "deleted_at": "2024-12-17T09:30:00Z"
  }
}

Request 1                Request 2                Request 3
──────────────────────────────────────────────────────────────
?limit=25         →      ?limit=25         →      ?limit=25
                         &cursor=ABC123           &cursor=XYZ789

┌────────────┐          ┌────────────┐          ┌────────────┐
│ Items 1-25 │          │ Items 26-50│          │ Items 51-75│
│            │          │            │          │            │
│  cursor:   │          │  cursor:   │          │  cursor:   │
│  ABC123    │          │  XYZ789    │          │   null     │
└────────────┘          └────────────┘          └────────────┘

curl "https://api.example.com/v1/items?limit=25"

{
  "data": [...],
  "meta": {
    "count": 25,
    "next_cursor": "eyJvZmZzZXQiOjI1fQ",
    "has_more": true
  }
}

curl "https://api.example.com/v1/items?limit=25&cursor=eyJvZmZzZXQiOjI1fQ"

curl "https://api.example.com/v1/items?status=active&q=electronics" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl "https://api.example.com/v1/items?sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl "https://api.example.com/v1/items?status=active&sort=updated_at&order=desc&limit=50&q=premium" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Rate Limit Window (1 minute)
────────────────────────────────────────────────────
0s                    30s                    60s
├──────────────────────┼──────────────────────┤
│ ████████████████████ │ ░░░░░░░░░░░░░░░░░░░░ │
│   60 requests used   │   0 requests left    │
└──────────────────────┴──────────────────────┘
                  Reset at 60s

# Example response headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1702814400

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Error Flow
──────────────────────────────────────────────────────
Client Request
     │
     ▼
┌─────────────┐
│ Validation  │──── Pass ────▶ Process Request
│             │
└─────────────┘
     │ Fail
     ▼
┌─────────────┐
│ Error       │
│ Response    │
│ + Details   │
└─────────────┘

{
  "error": {
    "type": "validation_error",
    "message": "The provided data is invalid.",
    "code": "INVALID_REQUEST",
    "details": [
      {
        "field": "name",
        "message": "Name must be between 3 and 100 characters.",
        "code": "length_out_of_range"
      }
    ],
    "request_id": "req_abc123xyz"
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters.",
    "code": "VALIDATION_FAILED"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or expired API token.",
    "code": "INVALID_TOKEN"
  }
}

{
  "error": {
    "type": "resource_not_found",
    "message": "The requested item could not be found.",
    "code": "NOT_FOUND"
  }
}

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "code": "RATE_LIMIT",
    "retry_after": 60
  }
}

Webhook Flow
────────────────────────────────────────────────────
Event Occurs
     │
     ▼
┌─────────────┐
│  API Server │
│             │
│  Triggers   │
│  Webhook    │
└─────────────┘
     │
     ▼
┌─────────────┐           ┌─────────────┐
│   POST      │─────────▶│ Your Server │
│  Request    │           │             │
│             │◀─────────│  200 OK     │
└─────────────┘           └─────────────┘

{
  "id": "evt_abc123",
  "type": "item.created",
  "created_at": "2024-12-17T10:00:00Z",
  "data": {
    "id": "it_126",
    "name": "New Item",
    "status": "active",
    "created_at": "2024-12-17T10:00:00Z"
  }
}

const crypto = require('crypto');
 
function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

const API_BASE = 'https://api.example.com/v1';
const TOKEN = 'YOUR_API_TOKEN';
 
const api = {
  async request(endpoint, options = {}) {
    const res = await fetch(`$\{API_BASE\}$\{endpoint\}`, {
      ...options,
      headers: {
        'Authorization': `Bearer $\{TOKEN\}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    if (!res.ok) throw new Error(await res.text());
    return res.json();
  },
  
  get: (endpoint) => api.request(endpoint),
  post: (endpoint, data) => api.request(endpoint, {
    method: 'POST',
    body: JSON.stringify(data)
  }),
  patch: (endpoint, data) => api.request(endpoint, {
    method: 'PATCH',
    body: JSON.stringify(data)
  }),
  delete: (endpoint) => api.request(endpoint, { method: 'DELETE' })
};
 
// Usage
const items = await api.get('/items?limit=10');
const newItem = await api.post('/items', { name: 'Test', status: 'active' });
await api.patch(`/items/${newItem.data.id}`, { status: 'archived' });
await api.delete(`/items/${newItem.data.id}`);

import requests
 
class API:
    def __init__(self, token):
        self.base = 'https://api.example.com/v1'
        self.headers = {
            'Authorization': f'Bearer \{token\}',
            'Content-Type': 'application/json'
        }
    
    def get(self, path, params=None):
        return requests.get(f'{self.base}\{path\}', 
                          headers=self.headers, params=params).json()
    
    def post(self, path, data):
        return requests.post(f'{self.base}\{path\}', 
                           headers=self.headers, json=data).json()
    
    def patch(self, path, data):
        return requests.patch(f'{self.base}\{path\}', 
                            headers=self.headers, json=data).json()
    
    def delete(self, path):
        return requests.delete(f'{self.base}\{path\}', 
                             headers=self.headers).json()
 
# Usage
api = API('YOUR_API_TOKEN')
items = api.get('/items', {'limit': 10})
new_item = api.post('/items', {'name': 'Test', 'status': 'active'})
api.patch(f'/items/{new_item["data"]["id"]}', {'status': 'archived'})
api.delete(f'/items/{new_item["data"]["id"]}')

<?php
class API {
    private $base = 'https://api.example.com/v1';
    private $token;
    
    public function __construct($token) {
        $this->token = $token;
    }
    
    private function request($method, $path, $data = null) {
        $ch = curl_init($this->base . $path);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->token,
                'Content-Type: application/json'
            ],
            CURLOPT_POSTFIELDS => $data ? json_encode($data) : null
        ]);
        $response = curl_exec($ch);
        curl_close($ch);
        return json_decode($response, true);
    }
    
    public function get($path, $params = []) {
        $query = http_build_query($params);
        return $this->request('GET', $path . ($query ? '?' . $query : ''));
    }
    
    public function post($path, $data) {
        return $this->request('POST', $path, $data);
    }
    
    public function patch($path, $data) {
        return $this->request('PATCH', $path, $data);
    }
    
    public function delete($path) {
        return $this->request('DELETE', $path);
    }
}
 
// Usage
$api = new API('YOUR_API_TOKEN');
$items = $api->get('/items', ['limit' => 10]);
$newItem = $api->post('/items', ['name' => 'Test', 'status' => 'active']);
$api->patch('/items/' . $newItem['data']['id'], ['status' => 'archived']);
$api->delete('/items/' . $newItem['data']['id']);
?>

require 'net/http'
require 'json'
 
class API
  BASE = 'https://api.example.com/v1'
  
  def initialize(token)
    @token = token
  end
  
  def request(method, path, data = nil)
    uri = URI("#\{BASE\}#\{path\}")
    req = Net::HTTP.const_get(method).new(uri)
    req['Authorization'] = "Bearer #{@token}"
    req['Content-Type'] = 'application/json'
    req.body = data.to_json if data
    
    res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(req)
    end
    JSON.parse(res.body)
  end
  
  def get(path, params = {})
    uri = URI("#\{BASE\}#\{path\}")
    uri.query = URI.encode_www_form(params) unless params.empty?
    request('Get', uri.request_uri)
  end
  
  def post(path, data)
    request('Post', path, data)
  end
  
  def patch(path, data)
    request('Patch', path, data)
  end
  
  def delete(path)
    request('Delete', path)
  end
end
 
# Usage
api = API.new('YOUR_API_TOKEN')
items = api.get('/items', limit: 10)
new_item = api.post('/items', { name: 'Test', status: 'active' })
api.patch("/items/#{new_item['data']['id']}", { status: 'archived' })
api.delete("/items/#{new_item['data']['id']}")