🌐 REST API Design Patterns

Standards for synchronous service communication.

Overview

SEA™ follows consistent REST API patterns for all synchronous communication:

Principle Implementation
Resource-oriented Noun-based URLs
HATEOAS Links in responses
Versioning URL path versioning
Idempotency Idempotency keys for mutations
Rate limiting Token bucket per client

URL Structure

Pattern

1

/api/v{version}/{resource}/{id?}/{sub-resource?}

Examples

1
2
3
4
5
6
7
8

GET    /api/v1/cases              # List cases
POST   /api/v1/cases              # Create case
GET    /api/v1/cases/{id}         # Get case
PATCH  /api/v1/cases/{id}         # Update case
DELETE /api/v1/cases/{id}         # Delete case

GET    /api/v1/cases/{id}/tasks   # List case tasks
POST   /api/v1/cases/{id}/tasks   # Create task in case

Request Headers

Header Required Purpose
Authorization Yes Bearer token
Content-Type Yes application/json
X-Request-Id No Tracing correlation
X-Idempotency-Key POST/PUT Prevent duplicates

Response Format

Success Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "data": {
    "id": "case-123",
    "type": "case",
    "attributes": {
      "title": "New Case",
      "status": "open"
    },
    "links": {
      "self": "/api/v1/cases/case-123",
      "tasks": "/api/v1/cases/case-123/tasks"
    }
  },
  "meta": {
    "requestId": "req-abc-123"
  }
}

Error Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {
        "field": "title",
        "code": "REQUIRED",
        "message": "Title is required"
      }
    ]
  },
  "meta": {
    "requestId": "req-abc-123"
  }
}

HTTP Status Codes

Code Usage
200 Success with body
201 Created
204 Success, no body
400 Validation error
401 Unauthenticated
403 Forbidden
404 Not found
409 Conflict (duplicate)
422 Unprocessable entity
429 Rate limited
500 Server error

Pagination

Request

1

GET /api/v1/cases?page=2&limit=20

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/v1/cases?page=2&limit=20",
    "first": "/api/v1/cases?page=1&limit=20",
    "prev": "/api/v1/cases?page=1&limit=20",
    "next": "/api/v1/cases?page=3&limit=20",
    "last": "/api/v1/cases?page=8&limit=20"
  }
}

Filtering & Sorting

Filter Syntax

1

GET /api/v1/cases?filter[status]=open&filter[priority]=high

Sort Syntax

1

GET /api/v1/cases?sort=-createdAt,title

Prefix - for descending order.

Idempotency

Pattern

1
2
3
4

# Client generates unique key
curl -X POST /api/v1/cases \
  -H "X-Idempotency-Key: client-uuid-123" \
  -d '{"title": "New Case"}'

Server Behavior

  1. Check if key exists in idempotency store
  2. If exists, return cached response
  3. If not, process request and cache response
  4. Key expires after 24 hours

Rate Limiting

Headers

1
2
3

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200

429 Response

1
2
3
4
5
6
7

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

OpenAPI Specification

All APIs are documented via OpenAPI 3.0:

1
2
3
4
5

# View API docs
open http://localhost:8000/docs

# Download spec
curl http://localhost:8000/openapi.json