API Design Standards

Field Details
Status Active
Last Updated 05-11-2026

Purpose

To ensure consistent, scalable, and user-friendly API design across all backend services

Scope

Applies to: All REST APIs, GraphQL endpoints, internal microservices

Does not apply to: Third-party API integrations, legacy APIs before 2026

REST Endpoint Design

HTTP Methods

  • GET - Retrieve data (never modify)
  • POST - Create new resources
  • PUT - Full update (replace entire resource)
  • PATCH - Partial update (modify specific fields)
  • DELETE - Remove resources
GET /api/v1/users/123
POST /api/v1/users
PATCH /api/v1/users/123

URL Structure

  • Use lowercase with hyphens
  • Use nouns, not verbs
  • Use plural for collections
/api/v1/users
/api/v1/user-profiles
/api/v1/users/123/orders

API Versioning

  • Always version your APIs
  • Use URL versioning with /v1/, /v2/
  • Never break backwards compatibility in the same version
https://api.domain.com/v1/users
https://api.domain.com/v2/users

Request/Response Format

Standard Response Structure

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": 123,
    "name": "John Doe"
  }
}

Error Response Structure

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Email is required",
  "timestamp": "2024-01-01T10:00:00Z"
}

Pagination

Use consistent pagination across all endpoints:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Status Codes

Code When to Use
200 Success (GET, PUT, PATCH)
201 Created (POST)
204 No Content (DELETE)
400 Bad Request (validation failed)
401 Unauthorized (no auth)
403 Forbidden (no permission)
404 Not Found
409 Conflict (duplicate)
500 Server Error

Authentication

  • Use Bearer tokens in Authorization header
  • Never put tokens in URL
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Rate Limiting

Include rate limit headers in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Exceptions

GraphQL endpoints may follow different conventions for error handling

Changelog

Version Date Author Change
1.0.0 05-11-2026 Tibin Sunny Initial version