/gateway

API Design Principles

API Design Philosophy

Gateway answers five critical questions:

Gateway designs and documents APIs. Implementation is delegated to Builder.

Coverage Scope

GraphQL Note: GraphQLのスキーマ設計（Query/Mutation/Type定義）はGatewayがカバーしますが、Resolver実装やDataLoader最適化はBuilderの責任範囲です。GraphQLプロジェクトでは、GatewayはSDL（Schema Definition Language）とドキュメントを生成し、実装詳細はBuilderに委譲します。

RESTful Design Checklist

URL Design Patterns

# Good patterns
GET    /api/v1/users              # List users
POST   /api/v1/users              # Create user
GET    /api/v1/users/{id}         # Get user
PUT    /api/v1/users/{id}         # Replace user
PATCH  /api/v1/users/{id}         # Update user
DELETE /api/v1/users/{id}         # Delete user

GET    /api/v1/users/{id}/orders  # User's orders
POST   /api/v1/users/{id}/orders  # Create order for user

# Query parameters
GET    /api/v1/users?status=active&limit=10&offset=0
GET    /api/v1/users?sort=created_at:desc
GET    /api/v1/users?fields=id,name,email

# Bad patterns (avoid)
GET    /api/v1/getUsers           # Verb in URL
POST   /api/v1/users/create       # Action in URL
GET    /api/v1/user               # Singular collection
DELETE /api/v1/users/delete/{id}  # Redundant action

HTTP Status Codes Reference

Idempotency

Idempotency Key Pattern

Allows clients to safely retry non-idempotent operations (POST, PATCH) without risk of duplicate resource creation.

POST /v1/payments
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "amount": 5000,
  "currency": "jpy",
  "customer_id": "cust_abc123"
}

Rules:

1. Accept Idempotency-Key header on all state-mutating endpoints (POST, PATCH, DELETE if non-idempotent).
2. Keys must be unique per operation — UUIDv4 is the standard format. Keys should be treated as opaque strings (do not parse).
3. Store the key + response atomically. Return the cached response on duplicate keys — do not re-execute the operation.
4. Scope key uniqueness to the authenticated caller, not globally — two different users may use the same key value independently.
5. Keys should expire after a configurable window (24–48 hours is typical). Return 409 Conflict with a clear message if an expired key is resubmitted for a new operation.