api-designer

Start by modeling resources and relationships, then define endpoints with proper HTTP methods and URIs. Write the OpenAPI 3.1 spec in YAML, validate it with npx @redocly/cli lint, and mock it with Prism to verify the contract before implementation.

Use offset or page-based pagination for small datasets needing random access and total counts. Use cursor or keyset pagination for large or frequently changing datasets, real-time feeds, and infinite scroll interfaces where consistency and performance matter.

Use RFC 7807 Problem Details with Content-Type application/problem+json, including type, title, status, detail, and instance fields. Add an errors array for field-level validation failures and always include a request ID for debugging.

Yes, define an HTTP bearer security scheme with bearerFormat JWT under components.securitySchemes, then apply it globally or per-operation. OAuth 2.0 flows and API keys are also supported as alternative schemes.

Create a new major version only for breaking changes such as removing fields, changing types, or altering response structures. URI versioning like /v1 and /v2 is recommended, with 6-12 month deprecation periods and Sunset headers before shutdown.