Rest

---
name: rest
description: "REST API design covering OpenAPI 3.1, HTTP semantics, resource design, pagination, caching, content negotiation, CORS, API gateways, rate limiting, and error handling. Use for \"REST API\", \"OpenAPI\", \"Swagger\", \"HTTP methods\", \"status codes\", \"CORS\", \"pagination\", \"API versioning\", \"rate limiting\", \"API gateway\", \"Kong\", \"APIM\", \"API design\", \"HATEOAS\", \"content negotiation\", \"ETag\", \"caching\", \"idempotency key\", \"RFC 9457\", \"Problem Details\", \"JSON:API\", \"HAL\". Covers protocol/design/versioning concerns. Do NOT use for framework-specific REST implementation (Express routing, FastAPI dependency injection, ASP.NET Core controllers) — use the relevant framework skill in the `backend` plugin."
license: MIT
---

# REST API Design

This skill covers REST API design: the full lifecycle from contract design (OpenAPI) through implementation, caching, authentication, gateway configuration, and troubleshooting. It has deep knowledge of:

- HTTP semantics (RFC 9110), methods, status codes, and content negotiation
- OpenAPI 3.1 specification, tooling, and code generation
- Resource-oriented URL design and Richardson Maturity Model
- Pagination patterns (offset, cursor, keyset, Link header)
- Caching (ETag, Cache-Control, conditional requests)
- Error handling (RFC 9457 Problem Details)
- API gateways (Kong, AWS API Gateway, Azure APIM, Apigee)
- CORS configuration and debugging
- Rate limiting, idempotency keys, and bulk operations

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **API design / URL structure** -- Load `references/architecture.md` for resource design, HTTP methods, status codes, content negotiation
   - **Performance / caching / best practices** -- Load `references/best-practices.md` for pagination, caching, versioning, error handling, gateway configuration
   - **Troubleshooting / diagnostics** -- Load `references/diagnostics.md` for CORS errors, status code confusion, gateway issues, performance problems
   - **Cross-protocol comparison** -- Read the `overview` skill for REST vs GraphQL, gRPC, etc.

2. **Gather context** -- API audience (public vs internal), existing spec format, gateway in use, client types, caching requirements

3. **Analyze** -- Apply REST principles. Resource-oriented design with correct HTTP semantics. Every design decision has trade-offs.

4. **Recommend** -- Provide actionable guidance with OpenAPI snippets, HTTP examples, and gateway configuration where appropriate.

5. **Verify** -- Suggest validation (Spectral linting, curl commands, Postman tests, gateway health checks).

## Core Architecture

### Resource-Oriented Design

Resources are nouns, not verbs. Design around entities:
- **Collections**: `/orders`, `/users`, `/products`
- **Items**: `/orders/{id}`, `/users/{id}`
- **Sub-resources**: `/orders/{id}/items`, `/users/{id}/addresses`
- **Singletons**: `/me`, `/config`

Anti-patterns: verb URLs (`/getUser`), mixed plural/singular, deep nesting beyond two levels.

### HTTP Method Semantics (RFC 9110)

| Method | Safe | Idempotent | Use |
|---|---|---|---|
| GET | Yes | Yes | Retrieve resource or collection |
| HEAD | Yes | Yes | Check existence, get headers only |
| POST | No | No | Create resource, trigger action |
| PUT | No | Yes | Full resource replacement |
| PATCH | No | No* | Partial update |
| DELETE | No | Yes | Remove resource |
| OPTIONS | Yes | Yes | CORS preflight, capability discovery |

*PATCH can be made idempotent with careful design (e.g., JSON Patch operations).

### Status Code Selection

**2xx:** 200 OK, 201 Created (+ Location header), 202 Accepted (async), 204 No Content (DELETE), 206 Partial Content.

**4xx:** 400 Bad Request, 401 Unauthorized (unauthenticated), 403 Forbidden (unauthorized), 404 Not Found, 405 Method Not Allowed, 409 Conflict, 422 Unprocessable Entity (validation), 429 Too Many Requests (+ Retry-After).

**5xx:** 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable (+ Retry-After), 504 Gateway Timeout.

**Rule:** Never return 200 OK with an error body. Status code must reflect success or failure.

### OpenAPI 3.1

The standard for REST API contracts. Key features in 3.1:
- Full JSON Schema 2020-12 alignment
- `type: ["string", "null"]` replaces `nullable: true`
- `webhooks` top-level field for callback descriptions
- `$ref` sibling properties now allowed

**Tooling:** Swagger UI, Redoc, Stoplight Studio, Spectral (linting), openapi-generator (50+ languages), oapi-codegen (Go), Scalar (modern docs).

### Content Negotiation

Client specifies format via `Accept` header. Server responds with `Content-Type`. Include `Vary: Accept` for cache correctness.

Common media types: `application/json`, `application/vnd.api+json` (JSON:API), `application/hal+json` (HAL), `application/problem+json` (errors), `application/merge-patch+json` (PATCH).

### API Gateways

| Gateway | Hosting | Best For |
|---|---|---|
| Kong | Self-hosted / Konnect | Plugin ecosystem, multi-cloud |
| AWS API Gateway | AWS managed | Serverless, Lambda integration |
| Azure APIM | Azure managed | Microsoft ecosystem, developer portal |
| Apigee | Google Cloud | Enterprise analytics, monetization |

Gateways handle: routing, authentication, rate limiting, transformation, TLS termination, observability, caching.

## Anti-Patterns

1. **Verb URLs** -- `/getUser`, `/createOrder`, `/deleteItem`. Use resource nouns with HTTP methods.
2. **200 OK with error body** -- Status codes must reflect the outcome. Use 4xx/5xx for errors.
3. **No versioning until v2** -- Version from day one. Adding versioning to a live API is painful.
4. **Ignoring CORS** -- Every browser-facing API needs proper CORS headers. Test preflight requests.
5. **Offset pagination on large datasets** -- Use cursor or keyset pagination for large, frequently-updated collections.
6. **No idempotency keys on POST** -- Payment and create operations must be safely retryable.
7. **Hardcoded credentials in gateway config** -- Use Key Vault, Secrets Manager, or environment-specific parameter files.
8. **Wildcard CORS with credentials** -- `Access-Control-Allow-Origin: *` is incompatible with `Access-Control-Allow-Credentials: true`.

## Reference Files

- `references/architecture.md` -- HTTP semantics, resource design, URL conventions, OpenAPI 3.1, status codes, content negotiation, HATEOAS, hypermedia formats (JSON:API, HAL)
- `references/best-practices.md` -- Pagination patterns, caching (ETag, Cache-Control), versioning strategies, error handling (RFC 9457), API gateways, rate limiting, idempotency keys, CORS, bulk operations, async patterns
- `references/diagnostics.md` -- CORS errors, 401 vs 403 confusion, content-type mismatches, pagination edge cases, gateway troubleshooting, rate limiting diagnostics, performance issues

## Cross-References

- `overview` skill -- cross-protocol comparisons
- `backend` plugin -- framework-specific REST implementation

## Diagnostic Scripts

Ready-made contract-validation script (read-only) in `scripts/`.

- `scripts/01-openapi-lint.sh` -- OpenAPI structural validity and REST design-smell lint