REST & OpenAPI Development for Well-Documented and Maintainable APIs

OpenAPI 2 (Swagger) uses a separate definitions object and has limited support for modern JSON Schema features. OpenAPI 3.0 introduced components, requestBody, and multiple response media types. OpenAPI 3.1 aligns fully with JSON Schema Draft 2020-12 — supporting nullable (null in type array), if/then/else, const, and deprecated in schemas. We use OpenAPI 3.1 for all new projects and migrate older specs to 3.1 during API reviews.

We use URL-prefix versioning (/v1/, /v2/) as the primary strategy — it is explicit, cacheable and visible in logs and API gateways. Header versioning (Accept: application/vnd.api.v2+json) is used for cases where URL stability matters (partner integrations). We maintain the previous version for a documented deprecation window (typically 6–12 months), add Sunset and Deprecation response headers to deprecated endpoints, and generate a changelog from OpenAPI spec diffs.

Language-specific tools generate OpenAPI from code annotations: Springdoc OpenAPI for Spring Boot (Java), FastAPI's built-in schema generation (Python), tsoa or ts-rest for TypeScript, oapi-codegen for Go. We run Spectral OpenAPI linting in CI to enforce naming conventions, required descriptions, example values and security scheme completeness. The generated spec is committed to the repository and published to a developer portal on each release.

Contract testing validates that a server implementation matches the contract defined in the OpenAPI spec. We use Prism (Stoplight) as a mock server — consumer teams write tests against Prism and the real server during development. Dredd or Schemathesis runs the OpenAPI spec as a test suite against the live server in CI — testing every endpoint, method and response code defined in the spec. A CI gate prevents merging if the implementation diverges from the spec.

OAuth2 with PKCE for user-facing APIs; client credentials flow for service-to-service; JWT validation at the API gateway layer (Kong, AWS API Gateway) with scope-based endpoint authorisation. Rate limiting per client_id and per IP via Redis counter. Input validation at the schema layer (JSON Schema validation before the handler runs). CORS restricted to known origins. Verbose error messages suppressed (no stack traces, no internal service details). OWASP API Security Top 10 review before each external launch.

A reverse proxy (Nginx, HAProxy) routes HTTP requests, terminates TLS and load-balances — it has no API-specific knowledge. An API gateway (Kong, AWS API Gateway, Azure APIM) adds API-specific middleware: auth plugin (JWT/OAuth2 validation), rate limiting per consumer, request/response transformation, logging per endpoint, developer portal and API versioning routing. We use Nginx as the reverse proxy at the edge and Kong or AWS API Gateway as the API gateway layer for API-specific concerns.

The OWASP API Security Top 10 is the industry-standard checklist for API vulnerabilities: 1) Broken Object Level Authorisation (BOLA — accessing other users' objects); 2) Broken Auth; 3) Broken Object Property Level Authorisation (mass assignment); 4) Unrestricted Resource Consumption (rate limiting missing); 5) Broken Function Level Authorisation (admin endpoints accessible to users); 6) Unrestricted Access to Sensitive Business Flows; 7) Server-Side Request Forgery (SSRF); 8) Security Misconfiguration; 9) Improper Inventory Management (shadow APIs); 10) Unsafe Consumption of APIs. We test every new API against all 10 before external launch.