skillbase/arch-api-design

## 1. Clarify API context

Before designing, establish:

- **Consumers**: internal services, mobile apps, third-party developers, browser SPA

- **Protocol fit**: REST for CRUD-heavy resources, gRPC for low-latency service-to-service, GraphQL for flexible client-driven queries

- **Lifecycle stage**: greenfield, extending existing API, or migration

- **Constraints**: existing conventions, auth mechanism, rate limiting, payload size limits

If the user has not specified the protocol, recommend one based on the use case and justify.

## 2. Design REST APIs

### Resource modeling

- Resources as nouns: `/orders`, `/users/{id}/addresses`

- Plural nouns for collections

- Nest max 2 levels (`/users/{id}/orders`) — deeper nesting increases coupling and makes URLs fragile when ownership changes

- Non-CRUD actions as verb sub-resources: `POST /orders/{id}/cancel`

### HTTP methods and status codes

Method, Semantics, Success Code, Idempotent

GET, Read resource, 200, Yes

POST, Create resource, 201, No

PUT, Full replace, 200, Yes

PATCH, Partial update, 200, Yes*

DELETE, Remove resource, 204, Yes

*PATCH is idempotent with JSON Merge Patch (RFC 7396) or JSON Patch (RFC 6902).

Return `Location` header on `201 Created`. Use `202 Accepted` for async operations with a status polling endpoint.

### Query design

- Pagination: cursor-based by default (`?cursor=xxx&limit=20`) — stable under concurrent writes, O(1) lookup vs O(n) offset skip. Use offset-based only for small stable datasets.

- Filtering: `?status=active&created_after=2024-01-01`

- Sorting: `?sort=created_at:desc`

- Field selection: `?fields=id,name,email`

### Request/response conventions

- `snake_case` for JSON fields — aligns with OpenAPI tooling and most backend languages. State explicitly if project uses `camelCase`.

- Wrap collections: `{ "data": [...], "pagination": { "next_cursor": "...", "has_more": true } }`

- Include `id`, `created_at`, `updated_at` in every resource

- Return full resource after create/update

## 3. Design gRPC APIs

### Proto file structure

- One proto file per service: `order/v1/order_service.proto`

- `package` matches directory: `package order.v1;`

- Define dedicated request/response messages per RPC — shared messages create hidden coupling between RPCs

### Naming conventions

- Services: `OrderService`, `PaymentService`

- RPCs: verb + noun — `CreateOrder`, `GetOrder`, `ListOrders`

- Messages: `CreateOrderRequest`, `CreateOrderResponse`

- Fields: `snake_case`, `google.protobuf.Timestamp` for times, `google.protobuf.FieldMask` for partial updates

### Streaming decisions

- Unary: default for request-response

- Server streaming: real-time feeds, large result sets

- Client streaming: bulk uploads, log ingestion

- Bidirectional: chat, collaborative editing

Use `repeated` for collections, `oneof` for mutually exclusive variants, wrapper types when null vs empty distinction matters.

## 4. Design GraphQL APIs

### Schema design

- Types map to domain entities, not database tables

- `ID!` scalar for identifiers

- Object types over primitives for extensibility: `Money { amount: Int!, currency: String! }`

- `Connection` pattern for pagination

### Query vs Mutation boundaries

- Queries: read-only, cacheable, no side effects

- Mutations: all writes, return the modified object

- Input types for mutation arguments: `createOrder(input: CreateOrderInput!): CreateOrderPayload!`

- Payloads include result and user errors: `CreateOrderPayload { order: Order, errors: [UserError!]! }`

### Performance guardrails

- Query depth limit (5-7 levels)

- Query complexity scoring and max cost

- Persistent queries or allowlisting for public APIs

- DataLoader for N+1 prevention

## 5. Versioning strategy

Strategy, Mechanism, Best for, Cost

URL path, /v1/orders, Public REST APIs, URL proliferation

Header, Accept-Version: v2, Internal APIs, Less discoverable

Content type, Accept: app/vnd.v2+json, Fine-grained evolution, Complex negotiation

Proto package, order.v2, gRPC services, Parallel maintenance

Schema evolution, @deprecated + new fields, GraphQL, Field accumulation

Defaults: REST public → URL path (`/v1/`), REST internal → header or backward-compatible evolution, gRPC → package-level, GraphQL → continuous evolution with `@deprecated`.

### Backward compatibility rules

**Safe** (non-breaking): adding optional response fields, new endpoints/RPCs, new enum values (if clients handle unknowns).

**Breaking**: removing/renaming fields, changing field types, making optional fields required, changing URL structure.

## 6. Error handling

### REST: RFC 9457 (Problem Details)

```json

{

  "type": "https://api.example.com/errors/insufficient-funds",

  "title": "Insufficient funds",

  "status": 422,

  "detail": "Account balance is 30.00, but transfer requires 50.00",

  "instance": "/transfers/txn-abc-123"

}

```

Status code mapping:

Code, Usage

400, Malformed request syntax

401, Missing or invalid authentication

403, Insufficient permissions

404, Resource not found

409, Conflict with current state

422, Semantic validation failed

429, Rate limit exceeded (include Retry-After)

500, Unexpected server error

502, Upstream dependency failure

503, Service temporarily unavailable

### gRPC: standard status codes

Use canonical codes: `NOT_FOUND`, `INVALID_ARGUMENT`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, `INTERNAL`. Include structured details via `google.rpc.Status`.

### GraphQL: typed error unions

Return domain errors in the response payload, use GraphQL-level errors only for transport/parsing failures:

```graphql

union CreateOrderResult = Order | InsufficientStockError | InvalidAddressError

```

### Cross-cutting error principles

- Every error includes a machine-readable code and human-readable message

- Return all validation errors at once

- Sanitize error responses to include only code, message, and correlation ID — stack traces and internal details belong in server logs

- Retriable errors indicate retry strategy (`Retry-After`, backoff hint)

## 7. Deliver the API specification

```

## API Overview

Purpose, consumers, protocol choice with justification.

## Resource/Service Model

Endpoints (REST), service definitions (gRPC), or schema (GraphQL).

## Contract Specification

OpenAPI 3.1 (REST), proto files (gRPC), or SDL (GraphQL).

## Versioning Strategy

Chosen approach with migration path.

## Error Handling

Error format, status code mapping, examples.

## Open Questions

Unresolved items.

```