klod68/api-design-standards

---

name: api-design-standards description: "Use when designing or reviewing RESTful HTTP APIs, endpoint routing, status codes, pagination, error responses, or OpenAPI specs in .NET projects."

Skill: RESTful API Design Standards

Identity

| Field | Value | |---|---| | Name | RESTful API Design Standards | | Domain | Web API, HTTP, REST | | Level | Feature | | Tags | api, rest, http, endpoints, pagination, openapi |

When to Apply

Activate this skill when the task involves:

• Designing or reviewing HTTP API endpoints
• Resource naming, URI structure, or route patterns
• HTTP method semantics and status code selection
• Pagination, filtering, or sorting strategies
• API error response formatting
• OpenAPI / Swagger specification

Rules

These rules layer on top of base architectural standards. On conflict, these win.

<!-- SHARED:rules/api-design.md -->

API Design — RESTful Conventions

Apply these rules in addition to _base.md for projects exposing HTTP APIs (Minimal API or MVC controllers).

---

Resource Naming

• URIs identify resources (nouns), never actions (verbs): /orders, /users/{id}/addresses — never /getOrders or /createUser.
• Use plural nouns for collection endpoints: /products, /categories.
• Use kebab-case for multi-word segments: /order-items, /shipping-addresses — never camelCase or snake_case in URIs.
• Nest resources only one level deep: /users/{id}/orders — never /users/{id}/orders/{orderId}/items/{itemId}. Access items directly: /order-items/{itemId}.
• API version prefix: /api/v1/orders — version in the path, not headers, unless the project has an explicit versioning strategy that overrides this default.

HTTP Method Semantics

| Method | Semantics | Idempotent | Safe | Typical Status | |--------|-----------|------------|------|----------------| | GET | Read resource(s) | Yes | Yes | 200 OK | | POST | Create resource | No | No | 201 Created + Location header | | PUT | Full replace of resource | Yes | No | 204 No Content | | PATCH | Partial update | No | No | 204 No Content | | DELETE | Remove resource | Yes | No | 204 No Content or 404 Not Found |

• Never use GET for operations with side effects.
• POST is the only method for non-idempotent operations — never overload GET with query parameters that trigger actions.
• PUT replaces the entire resource — if only updating partial fields, use PATCH.

Pagination

• Collection endpoints must support pagination — never return unbounded result sets.
• Use query parameters: ?page=1&pageSize=20 (offset-based) or ?cursor=abc&limit=20 (cursor-based).
• Response includes pagination metadata in the body — never in custom headers.

{
  "items": [...],
  "page": 1,
  "pageSize": 20,
  "totalCount": 142,
  "totalPages": 8
}

• Default page size is a policy value (settings class) — never hardcoded. Cap at a maximum (e.g., 100).
• Cursor-based pagination is preferred for large datasets — offset pagination degrades with deep pages.

Filtering, Sorting, Searching

• Filtering uses query parameters matching property names: ?status=active&category=electronics.
• Sorting uses a sort parameter with +/- prefix: ?sort=-createdAt,+name (descending by date, ascending by name).
• Full-text search uses a q parameter: ?q=wireless+headphones.
• Never expose raw SQL or OData syntax in query parameters — define an explicit filter vocabulary.

Error Responses

• All errors use RFC 7807 ProblemDetails format — never plain strings or custom error shapes.
• Validation errors return 400 Bad Request with a ValidationProblemDetails body including field-level errors.
• Business rule violations return 422 Unprocessable Entity with a descriptive ProblemDetails.
• Always include type, title, status, and detail — instance is optional.
• Never expose stack traces, internal paths, or connection strings in error responses.

{
  "type": "https://api.example.com/errors/insufficient-stock",
  "title": "Insufficient Stock",
  "status": 422,
  "detail": "Product SKU-123 has only 3 units available; 10 were requested.",
  "instance": "/api/v1/orders"
}

Request & Response Conventions

• Every endpoint has dedicated request and response DTOs — never reuse domain entities.
• Response DTOs are flat — avoid deep nesting. Use links or IDs for related resources instead of embedding.
• null fields are omitted from JSON output (JsonIgnoreCondition.WhenWritingNull) — never send explicit null for absent optional fields.
• Date/time values are ISO 8601 in UTC: "2024-12-15T14:30:00Z" — never local time or Unix timestamps.
• Monetary values include amount and currency: { "amount": 49.99, "currency": "USD" } — never bare numbers.

HATEOAS (When Applicable)

• Include _links for discoverable related actions only when the project adopts HATEOAS — not mandatory for internal APIs.
• Minimum links: self, collection-level next/prev for paginated resources.
• Link relations follow IANA registered types where applicable.

Idempotency

• PUT and DELETE are naturally idempotent — no extra work needed.
• For POST operations that must be idempotent (payment, order creation), accept an Idempotency-Key header.
• Store the key and response for a configurable window — return the cached response on duplicate requests.

Rate Limiting

• Public endpoints must declare rate limits — use .NET 7+ RateLimiter middleware.
• Return 429 Too Many Requests with a Retry-After header.
• Rate limit policies are per-endpoint or per-group — never a single global limit for all endpoints.
• Authentication endpoints have stricter limits than data endpoints.

OpenAPI / Documentation

• Every public API endpoint has XML documentation on its handler method.
• Use [ProducesResponseType] or .Produces<T>() for all possible status codes — not just the happy path.
• Include [Description] or [EndpointSummary] for OpenAPI metadata.
• Schema examples use [Example] attributes or Swashbuckle filters — never rely on default serialization output.

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | Verb in URI (/getOrders, /createUser) | Use nouns + HTTP methods: GET /orders, POST /users | | Unbounded collection endpoint | Add pagination with default + max page size | | Domain entity as response body | Map to dedicated response DTO | | Custom error format per endpoint | Use RFC 7807 ProblemDetails everywhere | | 200 OK for everything | Use semantically correct status codes | | CamelCase in URIs | Use kebab-case: /order-items | | Version in Accept header only | Default to URL prefix: /api/v1/ | | Hardcoded page size | Move to settings class with documented default and max cap | | Stack traces in error responses | Use ProblemDetails without internal details | | Local timestamps in responses | Always use ISO 8601 UTC |

---

See Also

• api-contracts.md — Interface-first design, return type abstractions, contract versioning
• minimal-api.md — Minimal API endpoint organization, handlers, filters, validation
• auth.md — Authentication, authorization, OAuth/OIDC, secrets management
• result-error-handling.md — Result object pattern, error constants, exception boundaries