- field baru ditambahkan,
- enum baru muncul,
- client lama belum upgrade,
- database schema berubah,
- error code berubah,
- retry behavior tidak jelas,
- long-running operation berubah dari sync ke async,
- satu consumer mengandalkan field internal,
- API Gateway validation tidak sinkron dengan application validation.

POST /orders
request body: OrderRequest
response body: OrderResponse

operation semantics,
command vs query,
authentication/authorization expectation,
required headers,
idempotency rule,
request schema,
response schema,
error schema,
state transition rule,
consistency expectation,
retry behavior,
pagination behavior,
versioning rule,
compatibility rule,
rate limit/quota expectation,
observability fields,
security redaction boundary.

api/
  openapi/
    orders.v1.yaml
  examples/
    create-order-request.json
    create-order-response-201.json
    error-validation-400.json
    error-conflict-409.json
  rules/
    api-lint.yaml
  tests/
    contract/
      create-order.compat.test.ts
      error-shape.compat.test.ts

can client retry?
should client retry?
what makes duplicate safe?
does success mean committed?
does 202 mean accepted but not done?
does GET read source or projection?
what conflict status is returned for invalid state transition?

- human-readable API review,
- generated documentation,
- request/response examples,
- API Gateway import/update,
- client SDK generation,
- server stub generation,
- schema validation,
- breaking change detection,
- contract tests,
- security review,
- API catalog.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create an order
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          $ref: '#/components/responses/ConflictError'

- generated SDK,
- documentation anchor,
- test naming,
- metrics naming,
- client code references,
- governance tooling.

operationId: postOrders
operationId: handler1
operationId: create

operationId: createOrder
operationId: cancelOrder
operationId: getOrder
operationId: listOrders
operationId: startImportJob

operationId expresses business operation, not HTTP mechanics.
operationId is stable unless operation meaning changes.
operationId must be unique across API.

{
  "order_table_customer_id": "cus_123",
  "order_status_cd": "P",
  "created_by_user_fk": 42
}

{
  "customerId": "cus_123",
  "items": [
    {
      "sku": "SKU-001",
      "quantity": 2
    }
  ],
  "shippingAddressId": "addr_456"
}

- jangan expose surrogate database fields yang tidak bermakna bagi client,
- jangan paksa client mengirim status internal,
- jangan expose foreign key raw jika domain id lebih stabil,
- jangan menerima field yang server seharusnya hitung sendiri,
- jangan menerima audit field dari client kecuali memang domain input.

{
  "status": "APPROVED",
  "approvedAt": "2026-07-06T01:00:00Z",
  "approvedBy": "u123"
}

{
  "decisionNote": "Evidence complete",
  "expectedVersion": 17
}

status = APPROVED
approvedAt = server time
approvedBy = authenticated principal

clients must ignore unknown response fields
clients must handle unknown enum values safely where documented
server must not require newly added request fields in same version

{}

{ "name": null }

{ "name": "" }

missing field means default/no change?
null means clear value?
empty string valid?
empty array valid?

{
  "displayName": null
}

- clear displayName?
- ignore field?
- invalid input?

{
  "displayName": {
    "op": "clear"
  }
}

{
  "amount": 10.5,
  "date": "07/06/2026"
}

- floating point precision,
- currency tidak jelas,
- timezone ambigu,
- format tanggal regional ambigu.

{
  "amount": {
    "currency": "USD",
    "minorUnits": 1050
  },
  "requestedAt": "2026-07-06T09:00:00Z"
}

money uses currency + integer minor units, or decimal string with explicit scale
instant uses ISO-8601 timestamp with timezone/UTC
local date uses YYYY-MM-DD only when business date is local-date semantic
never rely on server locale
never use float for money

{
  "type": "https://api.example.com/problems/validation-error",
  "code": "VALIDATION_ERROR",
  "message": "The request is invalid.",
  "traceId": "1-65f...",
  "retryable": false,
  "fieldErrors": [
    {
      "field": "items[0].quantity",
      "code": "MIN_VALUE",
      "message": "Quantity must be at least 1."
    }
  ]
}

- stack trace,
- SQL query,
- database host,
- internal class name,
- cloud resource ARN unless safe,
- IAM policy details,
- PII in error message.

VALIDATION_ERROR
AUTHENTICATION_REQUIRED
ACCESS_DENIED
RESOURCE_NOT_FOUND
IDEMPOTENCY_CONFLICT
ORDER_STATE_CONFLICT
QUOTA_EXCEEDED
RATE_LIMITED
TEMPORARILY_UNAVAILABLE
INTERNAL_ERROR

ERROR
FAILED
BAD_REQUEST
DB_ERROR
EXCEPTION

components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 16
        maxLength: 128
      description: >
        Stable client-generated key for retrying the same command safely.
        Reusing the same key with a different request body returns 409.

same key + same body -> same outcome
same key + different body -> 409 IDEMPOTENCY_CONFLICT
key retained for at least N hours/days
client must retry unknown timeout with same key
server may return in-progress status if first command still running

HTTP/1.1 201 Created
Idempotency-Key: ordcmd_01J...

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "The idempotency key was already used with a different command.",
  "traceId": "1-...",
  "retryable": false
}

{
  "expectedVersion": 17,
  "reason": "Evidence complete"
}

If-Match: "case-version-17"

HTTP/1.1 409 Conflict

{
  "code": "VERSION_CONFLICT",
  "message": "The case was modified by another operation.",
  "currentVersion": 18,
  "traceId": "1-...",
  "retryable": false
}

UPDATE regulatory_case
SET status = 'APPROVED', version = version + 1
WHERE case_id = :caseId
  AND version = :expectedVersion
  AND status = 'IN_REVIEW';

version conflict -> someone changed resource
invalid transition -> requested transition not allowed even on current state

GET /cases?status=OPEN

GET /cases?status=OPEN&pageSize=50&pageToken=eyJ...

{
  "items": [
    { "caseId": "case_001", "status": "OPEN" }
  ],
  "nextPageToken": "eyJ...",
  "pageSize": 50
}

page size has max limit
page token is opaque
client must not parse token
sort order documented
result consistency documented
filters indexed or bounded
expensive filters rejected or async exported

no unbounded offset pagination for huge tables
prefer keyset/cursor pagination
align query contract with index/access pattern
limit arbitrary sorting

pageToken maps to LastEvaluatedKey, but do not expose raw internal key if it leaks schema.

GET /orders?status=OPEN&customerId=cus_123&createdAfter=...

is it indexed?
is cardinality healthy?
can it be combined with other filters?
what is maximum result size?
what is latency SLO?
what happens if query becomes expensive?

Expose arbitrary filter/sort because frontend asked.

GET /cases?sortBy=anyField&filter=anyExpression

parameters:
  - name: status
    in: query
    schema:
      type: string
      enum: [OPEN, IN_REVIEW, ESCALATED, CLOSED]
  - name: assigneeId
    in: query
    schema:
      type: string
  - name: createdAfter
    in: query
    schema:
      type: string
      format: date-time

Gateway validation handles syntax/shape.
Application handles semantics.
Database enforces hard invariants.

x-amazon-apigateway-request-validators:
  all:
    validateRequestBody: true
    validateRequestParameters: true
x-amazon-apigateway-request-validator: all

components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - customerId
        - items
      additionalProperties: false
      properties:
        customerId:
          type: string
          minLength: 1
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/CreateOrderItem'
    CreateOrderItem:
      type: object
      required:
        - sku
        - quantity
      additionalProperties: false
      properties:
        sku:
          type: string
        quantity:
          type: integer
          minimum: 1
          maximum: 999

- catches typo fields,
- prevents unknown payload creep,
- stricter API contract.

- adding request fields can break old gateway validation if clients send future fields,
- can make compatibility harder for some clients,
- schema evolution must be deliberate.

x-amazon-apigateway-integration:
  type: aws_proxy
  httpMethod: POST
  uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/${CreateOrderFunctionArn}/invocations
  timeoutInMillis: 29000

OpenAPI now contains both public contract and deployment wiring.

api/openapi/orders.public.yaml
infra/cdk/api-gateway.ts

- clean public contract,
- infra code owns deployment,
- easier for external consumers.

- need tooling to ensure infra and contract stay aligned.

api/openapi/orders.apigateway.yaml

- API Gateway import directly uses contract,
- less duplication.

- AWS-specific config mixed into public spec,
- harder to share externally,
- environment substitution needed.

keep canonical contract clean,
generate deployable API Gateway spec from canonical contract + environment overlay.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create a new order
      description: >
        Creates an order command. This operation is idempotent by Idempotency-Key.
        If the same key is reused with a different request body, the server returns 409.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              minimal:
                value:
                  customerId: cus_123
                  items:
                    - sku: SKU-001
                      quantity: 2
      responses:
        '201':
          description: Order created
          headers:
            Location:
              schema:
                type: string
              description: URL of the created order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitedError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 16
        maxLength: 128
    CorrelationId:
      name: X-Correlation-Id
      in: header
      required: false
      schema:
        type: string
        maxLength: 128
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - customerId
        - items
      additionalProperties: false
      properties:
        customerId:
          type: string
          minLength: 1
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/CreateOrderItem'
    CreateOrderItem:
      type: object
      required:
        - sku
        - quantity
      additionalProperties: false
      properties:
        sku:
          type: string
          minLength: 1
        quantity:
          type: integer
          minimum: 1
          maximum: 999
    OrderResponse:
      type: object
      required:
        - orderId
        - status
        - version
        - createdAt
      properties:
        orderId:
          type: string
        status:
          type: string
          enum: [PENDING, CONFIRMED, CANCELLED]
        version:
          type: integer
          minimum: 1
        createdAt:
          type: string
          format: date-time
    Problem:
      type: object
      required:
        - code
        - message
        - traceId
        - retryable
      properties:
        type:
          type: string
        code:
          type: string
        message:
          type: string
        traceId:
          type: string
        retryable:
          type: boolean
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
    FieldError:
      type: object
      required: [field, code, message]
      properties:
        field:
          type: string
        code:
          type: string
        message:
          type: string
  responses:
    ValidationError:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    ConflictError:
      description: Conflict with current resource state or idempotency record
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimitedError:
      description: Request was throttled
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'

[ ] valid example request accepted
[ ] missing required field rejected
[ ] invalid type rejected
[ ] unknown field behavior matches contract
[ ] each documented error response can be produced
[ ] idempotency conflict returns documented 409 shape
[ ] timeout/overload returns stable error shape
[ ] response matches schema
[ ] correlation/trace id present in errors

[ ] consumer ignores unknown response field
[ ] consumer handles unknown enum fallback where required
[ ] consumer handles retryable=false
[ ] consumer handles 429 with backoff
[ ] consumer handles 202 async response if operation uses async pattern
[ ] consumer does not parse opaque pageToken
[ ] consumer does not rely on undocumented fields

[ ] API Gateway rejects malformed body before backend
[ ] API Gateway forwards required headers
[ ] API Gateway maps authorizer context correctly
[ ] API Gateway access log includes operation/request id
[ ] API Gateway error response is not raw backend exception
[ ] integration timeout behavior is understood

- remove endpoint,
- change HTTP method,
- remove response field,
- change field type,
- add required request field,
- remove enum value,
- add response enum without fallback policy,
- change status code semantics,
- remove error code,
- change pagination token semantics,
- change idempotency retention rule,
- change consistency guarantee.

GET /cases/{id} used to return source-of-truth state.
Now it returns eventually consistent projection.

/v1/orders
/v2/orders

clear routing,
easy parallel support,
easy deprecation communication.

coarse-grained,
can duplicate many endpoints,
clients may delay migration forever.

Accept: application/vnd.example.orders.v1+json

clean URI,
can version representation.

harder routing/operability,
less visible,
more client complexity.

keep same endpoint,
only additive compatible changes.

simpler,
works well with disciplined contracts.

requires strict compatibility discipline,
major semantic changes still need break mechanism.

avoid new major version for additive changes.
use major version only for semantic breaking changes.
combine with deprecation windows and consumer telemetry.

1. Identify consumers.
2. Measure endpoint/field usage.
3. Publish replacement contract.
4. Support dual behavior.
5. Add warning/deprecation headers if appropriate.
6. Notify consumers.
7. Monitor migration.
8. Enforce deadline.
9. Remove only after safety window.

Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrations/orders-v2>; rel="deprecation"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

which principal type can call this?
which tenant boundary applies?
which resource ownership rule applies?
which scopes/roles/permissions are required?
which fields are redacted by role?

x-domain-permissions:
  - case:approve
x-tenant-boundary: required
x-resource-ownership: case-assigned-or-supervisor

GET /orders/{id} -> primary key lookup
GET /orders?customerId=x -> index by customer
GET /orders?status=OPEN -> index/projection by status
GET /orders?text=abc -> search projection
POST /orders/{id}/cancel -> conditional state update
POST /orders/{id}/items -> aggregate mutation

what database access pattern does this require?
is it point lookup, range query, scan, graph traversal, search, aggregation?
which store owns source of truth?
is response from source DB, replica, projection, or cache?
what is freshness guarantee?
what is maximum cardinality?
what is the failure behavior if projection lags?

GET /cases?anyFieldContains=foo&sortBy=lastUpdated&includeHistory=true

source of truth should be repository, not exported console state.

- inspection,
- drift detection,
- migration from manual config,
- documentation bootstrap.

OpenAPI source in git
-> generate API Gateway deployable spec if needed
-> deploy via IaC/CI
-> run smoke test
-> optionally export deployed API
-> compare important pieces for drift

name: api-contract
on:
  pull_request:
    paths:
      - api/openapi/**

jobs:
  validate:
    steps:
      - checkout
      - run: openapi-lint api/openapi/orders.v1.yaml
      - run: openapi-diff --fail-on-breaking main:api/openapi/orders.v1.yaml api/openapi/orders.v1.yaml
      - run: run-contract-examples api/openapi/orders.v1.yaml
      - run: run-consumer-contract-tests

no operation without operationId
no 2xx response without schema
no 4xx/5xx response without Problem schema
no mutation without idempotency decision
no collection GET without pagination decision
no date-time without timezone semantics
no money number without currency/precision rule
no undocumented enum fallback
no endpoint without owner/team tag

[ ] Is this operation command, query, or async command?
[ ] Is the path named by domain semantics, not implementation detail?
[ ] Does request schema avoid database leakage?
[ ] Are required fields truly required from day one?
[ ] Are null/missing/empty semantics explicit?
[ ] Is money/time precision safe?
[ ] Is idempotency required for mutation?
[ ] Is optimistic concurrency needed?
[ ] Are error codes stable and actionable?
[ ] Are retry semantics documented?
[ ] Is pagination bounded?
[ ] Are filters backed by access patterns/indexes?
[ ] Is freshness/consistency documented?
[ ] Are auth/resource permissions clear?
[ ] Is API Gateway validation aligned with application validation?
[ ] Are examples included?
[ ] Are breaking change checks in CI?
[ ] Is observability/correlation defined?
[ ] Is deprecation/migration path possible?

JPA entity -> JSON response -> OpenAPI generated after the fact

- database schema leaks,
- lazy-loaded fields leak accidentally,
- internal rename becomes API breaking change,
- consumer sees fields not intended for public use.

CreateCaseRequest:
  type: object
  properties:
    title:
      type: string
    description:
      type: string

- validation moves to hidden code,
- docs lie,
- client gets late semantic errors,
- gateway cannot reject bad load.

switch (status) {
  case OPEN -> ...;
  case CLOSED -> ...;
  default -> throw new IllegalStateException();
}

- document enum expansion policy,
- provide UNKNOWN fallback in generated clients if possible,
- avoid exposing internal workflow states unless needed,
- distinguish public status from internal status.

PATCH /profile

- null ambiguity,
- partial update race,
- validation unclear,
- audit diff unclear.

NULL_POINTER_EXCEPTION
PSQL_EXCEPTION
TIMEOUT_EXCEPTION

client now depends on implementation failure.

POST /cases
GET /cases/{caseId}
POST /cases/{caseId}/assign
POST /cases/{caseId}/escalate
POST /cases/{caseId}/close
GET /cases?status=OPEN&assigneeId=...

{
  "expectedVersion": 12,
  "reasonCode": "SLA_RISK",
  "note": "Case has exceeded review threshold."
}

Idempotency-Key required? yes.
Expected version required? yes.
Can repeated same command succeed? yes, same outcome.
Invalid transition? 409 CASE_STATE_CONFLICT.
Missing evidence? 422 CASE_CLOSURE_REQUIREMENT_NOT_MET.
Audit event? CaseEscalated event emitted after DB commit.
Read freshness? GET /cases/{id} reads source DB for detail.
List freshness? GET /cases reads projection, eventually consistent.
Realtime update? WebSocket notification only, not source of truth.

what operation means,
what state it may change,
what request is valid,
what response means,
what errors mean,
what retry means,
what consistency is promised,
what compatibility is guaranteed,
what database access pattern is implied.

linted,
diffed,
validated,
deployed,
tested,
documented,
generated,
reviewed.

Do not let implementation shape become public contract by accident.