REST API Specification: [API name] v[1]

Complete specification for an HTTP/JSON API: environments, security, conventions, versioning, pagination, idempotency, rate limits, errors as RFC 9457 problem details, endpoint-by-endpoint contracts, streaming responses, webhooks, an OpenAPI 3.2 skeleton, changelog and service levels. Based on HTTP semantics (RFC 9110), Problem Details for HTTP APIs (RFC 9457) and the OpenAPI Specification 3.2.0 (published September 2025). Replace every [bracketed] value and every row marked Example. Worked examples use an order-management API.

Document control

Approvals

Revision history

Contents

1. Overview
2. Base URLs and environments
3. Authentication and authorisation
4. Conventions
5. Versioning and deprecation
6. Pagination, filtering and sorting
7. Idempotency and concurrency
8. Rate limiting
9. Errors
10. Resources and endpoints
11. Webhooks
12. OpenAPI 3.2 document
13. Changelog
14. Service levels and support
15. Glossary and references

1. Overview

1.1 Purpose

[What business capability the API exposes and for whom. Example: "The Orders API lets partner storefronts create, read, update and cancel customer orders, and subscribe to order status changes."]

1.2 Audience and scope

1.3 Resource model

The main resources and how they relate. Each resource has a stable, opaque identifier and its own collection URL.

2. Base URLs and environments

All environments accept TLS 1.2 or later only. Plain HTTP requests are rejected, not redirected, so that credentials are never sent in clear text.

3. Authentication and authorisation

3.1 Authentication methods

Token endpoint: [https://auth.example.com/oauth2/token]. Tokens are JWTs signed with [RS256 / ES256]; consumers must treat them as opaque. The authorization server publishes RFC 8414 metadata at [https://auth.example.com/.well-known/oauth-authorization-server], and the OpenAPI document points to it with oauth2MetadataUrl so tools can discover endpoints instead of hard-coding them. Schemes that are being retired are marked deprecated: true in the OpenAPI document (section 12).

3.2 Scopes

3.3 Authorisation rules

• A caller sees only orders belonging to its tenant (tenantId in the token). Requests for another tenant's order return 404, not 403, so that identifiers cannot be probed.
• Missing or invalid credentials return 401 with a WWW-Authenticate header. A valid token without the required scope returns 403.
• [Additional rule, for example field-level restrictions on personal data.]

4. Conventions

4.1 Resource naming and URLs

• Collections are plural nouns in kebab-case: /orders, /order-lines.
• Single resources: /orders/{orderId}. Nesting is limited to one level where the child cannot exist alone: /orders/{orderId}/shipments.
• Actions that do not map to CRUD use a sub-resource verb with POST: /orders/{orderId}/cancel.
• URLs never contain file extensions, trailing slashes or verbs for CRUD.

4.2 HTTP methods

Methods follow RFC 9110 semantics.

QUERY is the safe, idempotent method with a request body being standardised by the IETF HTTP working group; OpenAPI 3.2 describes it with the query operation field. Offer it only where gateways, proxies and client libraries in the consumer base support it, and keep an equivalent POST /orders/search while support is uneven. Any other non-standard method the API uses (for example PURGE on a cache endpoint) is described under additionalOperations in the OpenAPI document, never by overloading POST.

4.3 Data formats

4.4 Standard headers

4.5 Streaming and sequential responses

Long exports and live feeds are streamed as a sequence of items rather than one large JSON document, so clients can process each item as it arrives.

In OpenAPI 3.2 these responses declare itemSchema on the media type, so the schema validates each item in the stream independently; schema alone would describe the whole stream as one array.

5. Versioning and deprecation

5.1 Versioning scheme

The major version is in the path (/v1). Non-breaking changes are added to the current major version without notice beyond the changelog.

5.2 Deprecation policy

• Breaking changes ship in a new major version. The previous major version remains available for at least [12] months after the new one is GA.
• Deprecated endpoints return the Deprecation header (RFC 9745) with the date it was deprecated, and the Sunset header (RFC 8594) with the removal date, plus a Link header pointing to the migration guide.
• Consumers are notified by [email to registered contacts and the developer portal] at deprecation, at 90 days and at 30 days before sunset.

HTTP/1.1 200 OK
Deprecation: @1767225600
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://developer.example.com/orders/migrate-v2>; rel="deprecation"

6. Pagination, filtering and sorting

6.1 Cursor pagination

Collections return a page of items and an opaque cursor for the next page. Cursors expire after [24 hours] and must not be parsed by consumers.

{
  "data": [{"id": "ord_01HV6Z3K8Q", "status": "SHIPPED"}],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAzLTE0VDA5OjMwOjAwWiJ9",
  "hasMore": true
}

6.2 Filtering

Filters are query parameters named after the field. Multiple values are comma-separated and combined with OR; different fields combine with AND.

6.3 Sorting

sort takes a comma-separated list of fields; a leading - means descending. Default: -createdAt. Only fields listed per endpoint are sortable; others return 400 with problem type invalid-sort.

7. Idempotency and concurrency

7.1 Idempotency keys

• Every POST that creates a resource or moves money accepts an Idempotency-Key header (a client-generated UUID).
• The server stores the key, request fingerprint and response for [24 hours]. A repeat with the same key and body returns the stored response with header Idempotent-Replayed: true.
• The same key with a different body returns 422 with problem type idempotency-key-reused. A request still in progress returns 409.

7.2 Optimistic concurrency

GET responses include a strong ETag. PUT and PATCH require If-Match; a stale ETag returns 412 Precondition Failed, and a missing one returns 428 Precondition Required.

8. Rate limiting

Each response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). When the limit is exceeded the API returns 429 with a Retry-After header. Clients should retry with exponential backoff and jitter:

where $n$ is the retry attempt, $t_{base}$ = [0.5 s] and $t_{max}$ = [30 s].

9. Errors

9.1 Error format

Error responses use media type application/problem+json with the standard members type, title, status, detail and instance, plus the documented extension members below.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-Id: 4b1f0c2e-1d3a-4c7a-9a77-0b0c6a5e2f11

{
  "type": "https://api.example.com/problems/validation-failed",
  "title": "Request validation failed",
  "status": 422,
  "detail": "2 fields are invalid.",
  "instance": "/orders/v1/orders",
  "requestId": "4b1f0c2e-1d3a-4c7a-9a77-0b0c6a5e2f11",
  "errors": [
    {"pointer": "/lines/0/quantity", "detail": "must be at least 1"},
    {"pointer": "/shippingAddress/countryCode", "detail": "must be an ISO 3166-1 alpha-2 code"}
  ]
}

9.2 Problem type registry

10. Resources and endpoints

10.1 Endpoint summary

10.2 Orders: create an order (EP-02)

Creates an order in status PENDING_PAYMENT. Prices are taken from the catalogue at creation time; client-supplied prices are ignored.

POST /orders/v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Content-Type: application/json
Idempotency-Key: 0b8f6a2e-3c1d-4e5f-8a9b-1c2d3e4f5a6b

{
  "customerId": "cus_01HV5R2M7T",
  "lines": [{"sku": "TSHIRT-BLK-M", "quantity": 2}],
  "shippingAddress": {"line1": "12 Rue de Rivoli", "city": "Paris", "postalCode": "75001", "countryCode": "FR"}
}

HTTP/1.1 201 Created
Location: /orders/v1/orders/ord_01HV6Z3K8Q
ETag: "3f2a9c"
Content-Type: application/json

{
  "id": "ord_01HV6Z3K8Q",
  "status": "PENDING_PAYMENT",
  "customerId": "cus_01HV5R2M7T",
  "lines": [{"id": "lin_01HV6Z3KA1", "sku": "TSHIRT-BLK-M", "quantity": 2, "unitPrice": {"amount": "19.90", "currency": "EUR"}}],
  "totalAmount": {"amount": "39.80", "currency": "EUR"},
  "createdAt": "2026-03-14T09:30:00Z"
}

Side effects: emits webhook order.created (section 11).

10.3 Orders: list orders (EP-01)

Returns orders for the caller's tenant, newest first by default.

GET /orders/v1/orders?status=SHIPPED&limit=2 HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Response: 200 with the paginated envelope in section 6.1.

10.4 Orders: cancel an order (EP-05)

Cancels an order that has not shipped. Returns the updated order with status CANCELLED. An order with any shipment returns 409 with problem type order-not-cancellable. Calling cancel on an already cancelled order returns 200 with the unchanged order, so the action is idempotent.

10.5 [Resource]: [operation] ([EP-nn])

[Repeat the layout above for each remaining endpoint: purpose, parameter table, request example, response example, status table, side effects.]

11. Webhooks

11.1 Events

11.2 Delivery

• Payloads are POSTed as JSON to the subscriber's HTTPS URL with headers Webhook-Id, Webhook-Timestamp and Webhook-Signature.
• The signature is HMAC-SHA256 over id.timestamp.body with the subscription secret. Subscribers must verify it and reject timestamps older than [5 minutes] to block replays.
• A 2xx response within [10 s] acknowledges delivery. Other responses are retried with exponential backoff for [72 hours], then the subscription is marked failing and the owner notified.
• Delivery is at least once and not ordered. Subscribers deduplicate on Webhook-Id and use the occurredAt field to discard stale updates.

{
  "id": "evt_01HV7A0B2C",
  "type": "order.status_changed",
  "occurredAt": "2026-03-15T14:02:11Z",
  "data": {"orderId": "ord_01HV6Z3K8Q", "from": "PAID", "to": "SHIPPED"}
}

12. OpenAPI 3.2 document

The authoritative machine-readable contract is [api/openapi.yaml], written against OpenAPI 3.2.0.

12.1 Skeleton

The skeleton below shows the top-level structure, the shared components every endpoint reuses and one example of each 3.2 feature the API relies on.

openapi: 3.2.0
$self: https://api.example.com/orders/v1/openapi.yaml
info:
  title: Orders API
  version: 1.4.0
  contact:
    name: Orders team
    email: [email protected]
servers:
  - url: https://api.example.com/orders/v1
    description: Production
  - url: https://sandbox.api.example.com/orders/v1
    description: Sandbox
security:
  - oauth2: [orders:read]
tags:
  - name: Orders
    summary: Orders
    description: Create, read, update and cancel customer orders.
    kind: nav
  - name: Order exports
    summary: Exports
    parent: Orders
    kind: nav
  - name: Beta
    summary: Beta
    description: Endpoints that may change without a major version.
    kind: badge
paths:
  /orders:
    get:
      operationId: listOrders
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPage'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createOrder
      tags: [Orders]
      security:
        - oauth2: [orders:write]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        default:
          $ref: '#/components/responses/Problem'
    query:
      operationId: searchOrders
      summary: Search orders with a filter document in the body
      tags: [Orders, Beta]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderSearch'
      responses:
        '200':
          description: A page of matching orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPage'
        default:
          $ref: '#/components/responses/Problem'
  /orders/export:
    get:
      operationId: exportOrders
      tags: [Order exports]
      responses:
        '200':
          description: Orders streamed as JSON Lines, one order per line
          content:
            application/jsonl:
              itemSchema:
                $ref: '#/components/schemas/Order'
        default:
          $ref: '#/components/responses/Problem'
  /cache/orders/{orderId}:
    parameters:
      - name: orderId
        in: path
        required: true
        schema: {type: string}
    additionalOperations:
      PURGE:
        operationId: purgeOrderCache
        tags: [Orders]
        responses:
          '204':
            description: Cached representation removed
components:
  securitySchemes:
    oauth2:
      type: oauth2
      oauth2MetadataUrl: https://auth.example.com/.well-known/oauth-authorization-server
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth2/token
          scopes:
            orders:read: Read orders
            orders:write: Create and update orders
        deviceAuthorization:
          deviceAuthorizationUrl: https://auth.example.com/oauth2/device_authorization
          tokenUrl: https://auth.example.com/oauth2/token
          scopes:
            orders:read: Read orders
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      deprecated: true
  parameters:
    Limit:
      name: limit
      in: query
      schema: {type: integer, minimum: 1, maximum: 100, default: 25}
    Cursor:
      name: cursor
      in: query
      schema: {type: string}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: {type: string, format: uuid}
  responses:
    Problem:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    Problem:
      type: object
      properties:
        type: {type: string, format: uri}
        title: {type: string}
        status: {type: integer}
        detail: {type: string}
        instance: {type: string}
    Order:
      type: object
      required: [id, status, customerId, lines, totalAmount, createdAt]
      properties:
        id: {type: string, pattern: '^ord_'}
        status: {type: string, enum: [PENDING_PAYMENT, PAID, SHIPPED, DELIVERED, CANCELLED]}
        customerId: {type: string}
        lines: {type: array, items: {$ref: '#/components/schemas/OrderLine'}}
        totalAmount: {$ref: '#/components/schemas/Money'}
        createdAt: {type: string, format: date-time}
    OrderSearch:
      type: object
      properties:
        status: {type: array, items: {type: string}}
        customerIds: {type: array, maxItems: 500, items: {type: string}}
        createdAfter: {type: string, format: date-time}
    OrderCreate:
      type: object
      required: [customerId, lines, shippingAddress]
      properties:
        customerId: {type: string}
        lines: {type: array, minItems: 1, maxItems: 200, items: {type: object}}
        shippingAddress: {type: object}
    OrderLine:
      type: object
      properties:
        id: {type: string}
        sku: {type: string}
        quantity: {type: integer, minimum: 1}
        unitPrice: {$ref: '#/components/schemas/Money'}
    OrderPage:
      type: object
      properties:
        data: {type: array, items: {$ref: '#/components/schemas/Order'}}
        nextCursor: {type: [string, 'null']}
        hasMore: {type: boolean}
    Money:
      type: object
      required: [amount, currency]
      properties:
        amount: {type: string, pattern: '^-?\d+(\.\d{1,4})?$'}
        currency: {type: string, minLength: 3, maxLength: 3}

12.2 OpenAPI 3.2 features used

Version 3.2.0 adds the features below. Record which ones the API uses so that consumers can check their tooling supports them.

12.3 Validation rules

Validation rules for the OpenAPI file:

13. Changelog

14. Service levels and support

14.1 Service level objectives

Availability is computed as:

At 99.95% the monthly error budget is $0.0005 \times 30 \times 24 \times 60 \approx 21.6$ minutes of full outage.

14.2 Maintenance and support

15. Glossary and references

15.1 Glossary

15.2 References

Standard and licence note

Based on the IETF specifications RFC 9110 (HTTP Semantics) and RFC 9457 (Problem Details for HTTP APIs) and on the OpenAPI Specification 3.2.0 (September 2025, Apache License 2.0), together with common industry practice for API design. This template is original text written for this collection and reproduces no text from those specifications; read them for their normative requirements. Example values are illustrative. Template licence: MIT.