Code snippets — Rest Api Design Principles

snippet-2.json

{
  "data": [...],
  "meta": {
    "total": 1543,
    "page": 2,
    "per_page": 20,
    "next_cursor": "eyJpZCI6MTIwfQ"
  }
}

snippet-2.txt

/users           # collection
/users/42        # single resource
/users/42/posts  # nested resource

snippet-3.txt

200 OK          — Success, returning data
201 Created     — Resource created (POST)
204 No Content  — Success, nothing to return (DELETE)
400 Bad Request — Client sent invalid data
401 Unauthorized — Authentication required
403 Forbidden    — Authenticated but not authorized
404 Not Found    — Resource doesn't exist
409 Conflict     — State conflict (duplicate, etc.)
422 Unprocessable Entity — Validation failed
429 Too Many Requests    — Rate limited
500 Internal Server Error — Your bug

snippet-4.txt

/api/v1/users
/api/v2/users

snippet-5.txt

Accept: application/vnd.myapp.v2+json

snippet-6.txt

# Offset pagination
GET /users?page=2&per_page=20

# Cursor pagination (better for large datasets)
GET /users?cursor=eyJpZCI6MTAwfQ&limit=20

snippet-7.txt

GET /users?status=active&role=admin&sort=created_at&order=desc

snippet-8.txt

Content-Type: application/json
Accept: application/json

snippet-9.txt

POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "amount": 9900,
  "currency": "USD"
}

snippet.json

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

snippet.txt

# Bad
GET /getUsers
POST /createUser
DELETE /deleteUser/42

# Good
GET    /users
POST   /users
DELETE /users/42

snippet.yaml

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'