daffy0208/ai-dev-standards/api-designer

✅ Good (Nouns, plural, hierarchical):
GET    /users                  # List all users
GET    /users/123              # Get specific user
POST   /users                  # Create user
PUT    /users/123              # Replace user
PATCH  /users/123              # Update user
DELETE /users/123              # Delete user
GET    /users/123/posts        # User's posts (nested)
GET    /users/123/posts/456    # Specific post
 
❌ Bad (Verbs, inconsistent, unclear):
GET /getUsers
POST /createUser
GET /user-list
GET /UserData?id=123

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2025-01-15T10:30:00Z"
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "REQUIRED",
        "message": "Email is required"
      },
      {
        "field": "age",
        "code": "OUT_OF_RANGE",
        "message": "Age must be between 18 and 120"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors/validation"
  }
}

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "total_count": 1000
  },
  "links": {
    "next": "/users?cursor=eyJpZCI6MTIzfQ==&limit=20",
    "prev": "/users?cursor=eyJpZCI6MTAwfQ==&limit=20"
  }
}

GET /users?cursor=abc123&limit=20
 
Pros: Consistent results, efficient, handles real-time data
Cons: Can't jump to arbitrary page
Use when: Large datasets, real-time data, performance critical

GET /users?page=1&per_page=20
GET /users?offset=0&limit=20
 
Pros: Simple, can jump to any page
Cons: Inconsistent with concurrent writes, inefficient at scale
Use when: Small datasets, admin interfaces, simple use cases

GET /users?status=active&role=admin&created_after=2025-01-01

GET /users?sort=-created_at,name  # Descending created_at, then ascending name

GET /users?q=john&fields=name,email  # Search across specified fields

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 
Pros: Stateless, includes user claims, works across domains
Cons: Can't revoke until expiry, larger payload

X-API-Key: sk_live_abc123...
 
Pros: Simple, easy to rotate, per-service keys
Cons: No user context, must be kept secret

Authorization: Bearer access_token
 
Pros: Delegated auth, scoped permissions, industry standard
Cons: Complex setup, requires OAuth server

Authorization: Basic base64(username:password)
 
Pros: Simple, built-in to HTTP
Cons: Credentials in every request, must use HTTPS

X-RateLimit-Limit: 1000          # Max requests per window
X-RateLimit-Remaining: 999       # Requests left
X-RateLimit-Reset: 1640995200    # Unix timestamp when limit resets
Retry-After: 60                  # Seconds to wait (on 429)

/v1/users
/v2/users
 
Pros: Explicit, easy to route, clear in logs
Cons: URL pollution, harder to evolve incrementally

Accept: application/vnd.myapp.v2+json
API-Version: 2
 
Pros: Clean URLs, follows REST principles
Cons: Less visible, harder to test in browser

type User {
  id: ID!
  name: String!
  email: String!
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
}
 
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}
 
type PostEdge {
  node: Post!
  cursor: String!
}
 
type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}
 
type Query {
  user(id: ID!): User
  users(first: Int, after: String): UserConnection!
}
 
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}
 
input CreateUserInput {
  name: String!
  email: String!
}
 
type CreateUserPayload {
  user: User
  errors: [Error!]
}

query {
  users(first: 10, after: "cursor") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# ✅ Good: Input type + payload
mutation {
  createUser(input: { name: "John", email: "john@example.com" }) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}
 
# ❌ Bad: Flat arguments
mutation {
  createUser(name: "John", email: "john@example.com") {
    id
    name
  }
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}
 
type CreateUserPayload {
  user: User # Null if errors
  errors: [Error!] # Field-level errors
}
 
type Error {
  field: String!
  code: String!
  message: String!
}

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users and posts
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT