API Examples

Real-world REST API patterns with complete request and response examples

Users API

Complete CRUD operations for user management.

List Users with Pagination

GET /api/v1/users?page=1&limit=10&status=active

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Response (200 OK):

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin",
      "status": "active",
      "avatar_url": "https://api.example.com/avatars/1.jpg",
      "created_at": "2023-01-15T10:30:00Z",
      "updated_at": "2023-06-20T14:00:00Z"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "user",
      "status": "active",
      "avatar_url": null,
      "created_at": "2023-02-20T08:15:00Z",
      "updated_at": "2023-02-20T08:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "total_pages": 15,
    "has_next": true,
    "has_prev": false
  },
  "links": {
    "self": "/api/v1/users?page=1&limit=10&status=active",
    "next": "/api/v1/users?page=2&limit=10&status=active",
    "last": "/api/v1/users?page=15&limit=10&status=active"
  }
}

Get Single User

GET /api/v1/users/123

Response (200 OK):

{
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "role": "admin",
    "status": "active",
    "avatar_url": "https://api.example.com/avatars/123.jpg",
    "profile": {
      "bio": "Software developer and API enthusiast",
      "location": "San Francisco, CA",
      "website": "https://johndoe.dev"
    },
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-06-20T14:00:00Z"
  }
}

Response (404 Not Found):

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID 999 not found",
    "request_id": "req_abc123"
  }
}

Create User

POST /api/v1/users

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

Request Body:

{
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "password": "SecureP@ssw0rd!",
  "role": "user",
  "profile": {
    "bio": "New to the platform",
    "location": "New York, NY"
  }
}

Response (201 Created):

HTTP/1.1 201 Created
Location: /api/v1/users/124

{
  "data": {
    "id": 124,
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "user",
    "status": "pending_verification",
    "profile": {
      "bio": "New to the platform",
      "location": "New York, NY"
    },
    "created_at": "2023-06-21T09:00:00Z"
  }
}

Response (422 Unprocessable Entity):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "code": "ALREADY_EXISTS",
        "message": "This email is already registered"
      },
      {
        "field": "password",
        "code": "TOO_WEAK",
        "message": "Password must contain at least one uppercase letter"
      }
    ]
  }
}

Update User (Partial)

PATCH /api/v1/users/123

Request Body:

{
  "name": "John D. Doe",
  "profile": {
    "bio": "Senior software developer and API enthusiast"
  }
}

Response (200 OK):

{
  "data": {
    "id": 123,
    "name": "John D. Doe",
    "email": "john@example.com",
    "profile": {
      "bio": "Senior software developer and API enthusiast",
      "location": "San Francisco, CA",
      "website": "https://johndoe.dev"
    },
    "updated_at": "2023-06-21T10:00:00Z"
  }
}

Delete User

DELETE /api/v1/users/123

Response (204 No Content):

HTTP/1.1 204 No Content
// Empty body

Products API

E-commerce product management with filtering and search.

Search Products with Filters

GET /api/v1/products?category=electronics&price_min=50&price_max=500&sort=-rating&in_stock=true

Response (200 OK):

{
  "data": [
    {
      "id": 456,
      "name": "Wireless Bluetooth Headphones",
      "slug": "wireless-bluetooth-headphones",
      "description": "Premium noise-canceling wireless headphones",
      "price": 199.99,
      "currency": "USD",
      "category": {
        "id": 10,
        "name": "Electronics",
        "slug": "electronics"
      },
      "images": [
        {
          "url": "https://cdn.example.com/products/456/main.jpg",
          "alt": "Headphones front view",
          "is_primary": true
        },
        {
          "url": "https://cdn.example.com/products/456/side.jpg",
          "alt": "Headphones side view",
          "is_primary": false
        }
      ],
      "attributes": {
        "color": "Black",
        "brand": "AudioTech",
        "battery_life": "30 hours"
      },
      "stock": {
        "quantity": 150,
        "in_stock": true,
        "low_stock_threshold": 20
      },
      "rating": {
        "average": 4.7,
        "count": 1250
      },
      "created_at": "2023-03-10T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  },
  "filters_applied": {
    "category": "electronics",
    "price_range": {"min": 50, "max": 500},
    "in_stock": true
  }
}

Create Product

POST /api/v1/products

Request Body:

{
  "name": "Smart Watch Pro",
  "description": "Advanced fitness tracking smartwatch",
  "price": 299.99,
  "currency": "USD",
  "category_id": 10,
  "sku": "SW-PRO-001",
  "attributes": {
    "color": "Silver",
    "brand": "TechTime",
    "water_resistance": "50m"
  },
  "stock": {
    "quantity": 500,
    "low_stock_threshold": 50
  }
}

Response (201 Created):

{
  "data": {
    "id": 789,
    "name": "Smart Watch Pro",
    "slug": "smart-watch-pro",
    "sku": "SW-PRO-001",
    "price": 299.99,
    "currency": "USD",
    "status": "draft",
    "created_at": "2023-06-21T11:00:00Z"
  }
}

Orders API

Order management with nested resources and state transitions.

Create Order

POST /api/v1/orders

Request Body:

{
  "items": [
    {
      "product_id": 456,
      "quantity": 2,
      "variant_id": "color-black"
    },
    {
      "product_id": 789,
      "quantity": 1
    }
  ],
  "shipping_address": {
    "name": "John Doe",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US",
    "phone": "+1-555-123-4567"
  },
  "billing_address_same_as_shipping": true,
  "payment_method_id": "pm_card_visa",
  "coupon_code": "SAVE20"
}

Response (201 Created):

{
  "data": {
    "id": "ord_abc123def456",
    "order_number": "ORD-2023-001234",
    "status": "pending_payment",
    "items": [
      {
        "id": "item_001",
        "product_id": 456,
        "product_name": "Wireless Bluetooth Headphones",
        "quantity": 2,
        "unit_price": 199.99,
        "subtotal": 399.98
      },
      {
        "id": "item_002",
        "product_id": 789,
        "product_name": "Smart Watch Pro",
        "quantity": 1,
        "unit_price": 299.99,
        "subtotal": 299.99
      }
    ],
    "subtotal": 699.97,
    "discount": {
      "code": "SAVE20",
      "amount": 139.99,
      "type": "percentage",
      "value": 20
    },
    "shipping": {
      "method": "standard",
      "cost": 9.99,
      "estimated_delivery": "2023-06-28"
    },
    "tax": 44.80,
    "total": 614.77,
    "currency": "USD",
    "payment_status": "pending",
    "created_at": "2023-06-21T12:00:00Z"
  },
  "links": {
    "self": "/api/v1/orders/ord_abc123def456",
    "payment": "/api/v1/orders/ord_abc123def456/pay"
  }
}

Get Order with Items

GET /api/v1/orders/ord_abc123def456?include=items,shipping

Response (200 OK):

{
  "data": {
    "id": "ord_abc123def456",
    "order_number": "ORD-2023-001234",
    "status": "shipped",
    "items": [...],
    "shipping": {
      "method": "standard",
      "carrier": "FedEx",
      "tracking_number": "1234567890",
      "tracking_url": "https://fedex.com/track/1234567890",
      "shipped_at": "2023-06-22T09:00:00Z",
      "estimated_delivery": "2023-06-28"
    },
    "timeline": [
      {"status": "created", "at": "2023-06-21T12:00:00Z"},
      {"status": "paid", "at": "2023-06-21T12:05:00Z"},
      {"status": "processing", "at": "2023-06-21T14:00:00Z"},
      {"status": "shipped", "at": "2023-06-22T09:00:00Z"}
    ]
  }
}

Cancel Order

POST /api/v1/orders/ord_abc123def456/cancel

Request Body:

{
  "reason": "Changed my mind",
  "refund_to_original_payment": true
}

Response (200 OK):

{
  "data": {
    "id": "ord_abc123def456",
    "status": "cancelled",
    "cancellation": {
      "reason": "Changed my mind",
      "cancelled_at": "2023-06-21T13:00:00Z",
      "refund": {
        "id": "ref_xyz789",
        "amount": 614.77,
        "status": "processing",
        "estimated_completion": "2023-06-24"
      }
    }
  }
}

Response (409 Conflict - Order already shipped):

{
  "error": {
    "code": "ORDER_CANNOT_BE_CANCELLED",
    "message": "Order has already been shipped and cannot be cancelled",
    "suggestion": "Please initiate a return instead",
    "links": {
      "return": "/api/v1/orders/ord_abc123def456/return"
    }
  }
}

Authentication API

User authentication with JWT tokens.

Login

POST /api/v1/auth/login

Request Body:

{
  "email": "john@example.com",
  "password": "SecureP@ssw0rd!"
}

Response (200 OK):

{
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com",
      "role": "admin"
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 3600
    }
  }
}

Response (401 Unauthorized):

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect"
  }
}

Refresh Token

POST /api/v1/auth/refresh

Request Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "data": {
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 3600
    }
  }
}

Register

POST /api/v1/auth/register

Request Body:

{
  "name": "New User",
  "email": "newuser@example.com",
  "password": "SecureP@ssw0rd!",
  "password_confirmation": "SecureP@ssw0rd!",
  "terms_accepted": true
}

Response (201 Created):

{
  "data": {
    "user": {
      "id": 125,
      "name": "New User",
      "email": "newuser@example.com",
      "status": "pending_verification"
    },
    "message": "Please check your email to verify your account"
  }
}

Logout

POST /api/v1/auth/logout

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response (204 No Content):

HTTP/1.1 204 No Content

File Upload API

Handling file uploads with multipart form data.

Upload File (Multipart)

POST /api/v1/files/upload

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

Form Data:

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

[binary file data]
------WebKitFormBoundary
Content-Disposition: form-data; name="folder"

documents
------WebKitFormBoundary--

Response (201 Created):

{
  "data": {
    "id": "file_abc123",
    "name": "document.pdf",
    "original_name": "document.pdf",
    "mime_type": "application/pdf",
    "size": 1048576,
    "size_human": "1 MB",
    "url": "https://cdn.example.com/files/documents/file_abc123.pdf",
    "folder": "documents",
    "uploaded_at": "2023-06-21T14:00:00Z"
  }
}

Get Presigned Upload URL

For large files, use presigned URLs to upload directly to cloud storage.

POST /api/v1/files/presign

Request Body:

{
  "filename": "large-video.mp4",
  "content_type": "video/mp4",
  "size": 104857600
}

Response (200 OK):

{
  "data": {
    "upload_url": "https://s3.amazonaws.com/bucket/...?X-Amz-Signature=...",
    "file_id": "file_xyz789",
    "expires_at": "2023-06-21T15:00:00Z",
    "instructions": {
      "method": "PUT",
      "headers": {
        "Content-Type": "video/mp4"
      }
    }
  }
}

Webhooks API

Managing webhook subscriptions for event notifications.

Create Webhook Subscription

POST /api/v1/webhooks

Request Body:

{
  "url": "https://your-server.com/webhooks/orders",
  "events": [
    "order.created",
    "order.paid",
    "order.shipped",
    "order.delivered",
    "order.cancelled"
  ],
  "secret": "whsec_your_webhook_secret"
}

Response (201 Created):

{
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhooks/orders",
    "events": [
      "order.created",
      "order.paid",
      "order.shipped",
      "order.delivered",
      "order.cancelled"
    ],
    "status": "active",
    "created_at": "2023-06-21T15:00:00Z"
  }
}

Webhook Payload Example

This is what your server will receive when events occur.

POST to your webhook URL:

POST /webhooks/orders HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-Event: order.shipped
X-Webhook-Delivery: del_xyz789

{
  "id": "evt_abc123",
  "type": "order.shipped",
  "created_at": "2023-06-22T09:00:00Z",
  "data": {
    "order": {
      "id": "ord_abc123def456",
      "order_number": "ORD-2023-001234",
      "status": "shipped",
      "tracking_number": "1234567890"
    }
  }
}

Continue Learning

🔧 HTTP Methods

Deep dive into GET, POST, PUT, PATCH, DELETE.

📊 Status Codes

Complete reference for HTTP response codes.

🔐 Authentication

OAuth 2.0, JWT, API keys, and security.

📄 Pagination

Handle large datasets with pagination.

⚠️ Error Handling

Design helpful error responses.

🚦 Rate Limiting

Protect your API from abuse.