Name: Rest Api Standards
Author: spallempati

Universal Principles

Spec-First Development – OpenAPI contract MUST be authored (or updated) before implementation code is merged.
Versioning – API major version MUST appear in the path (/api/v{major}/…) and in the info.version field.
Consistent Envelope – Error responses MUST follow { code, message, data }; success bodies SHOULD wrap data similarly.
Security Schemes – Auth MUST be declared with type: http, scheme: bearer, bearerFormat: JWT; scopes live under components/securitySchemes.
Traceability – traceparent and baggage headers MUST be documented under components/headers so clients propagate OpenTelemetry context.
Pagination – Collections SHOULD use / parameters; responses include cursor link.

Spec-First Development – OpenAPI contract MUST be authored (or updated) before implementation code is merged.
Versioning – API major version MUST appear in the path (/api/v{major}/…) and in the info.version field.
Consistent Envelope – Error responses MUST follow { code, message, data }; success bodies SHOULD wrap data similarly.
Security Schemes – Auth MUST be declared with type: http, scheme: bearer, bearerFormat: JWT; scopes live under components/securitySchemes.
Traceability – traceparent and baggage headers MUST be documented under components/headers so clients propagate OpenTelemetry context.
Pagination – Collections SHOULD use / parameters; responses include cursor link.

Rest Api Standards