coder-system-design-api-design

name	coder-system-design-api-design
description	API design rules for stable, observable, backward-compatible HTTP APIs.

<when_to_use> Designing new HTTP APIs or evolving existing contracts Reviewing API changes for compatibility and client impact Defining versioning, error model, pagination, and idempotency </when_to_use>

<input_requirements> API consumers and usage patterns Resource model and operation set Compatibility policy and deprecation expectations Operational requirements (SLOs, observability, rate limits) </input_requirements>

<design_rules> Model nouns as resources and use HTTP semantics consistently Define one explicit versioning strategy and enforce it platform-wide Use machine-readable error format with stable codes/types Support idempotency for mutating operations with retries Ship pagination from first release for list endpoints Keep filtering/sorting grammar explicit and validated Require request correlation and trace propagation headers Treat backward compatibility as mandatory default in same major version Use explicit deprecation timeline and sunset communication </design_rules>

<decision_matrix> Versioning: path major for public API unless platform standard mandates header/query versioning Error model: prefer RFC 9457 problem details over custom ad-hoc envelopes Pagination: cursor/page token for mutable datasets; offset only for small stable datasets </decision_matrix>

Status codes are accurate and documented per operation Error payload includes stable identifier and actionable detail Idempotency behavior is documented for retries and duplicate submission List endpoints define page size bounds and continuation token behavior Compatibility impact is evaluated for each contract change

<do_not> Do not introduce breaking field or behavior changes in same major version Do not require clients to parse free-text error messages Do not add pagination later for high-volume endpoints </do_not>

<output_requirements> API contract summary with versioning and compatibility notes Error model and idempotency strategy Pagination/filtering contract and limits Observability and deprecation plan </output_requirements>

RFC 9110 HTTP Semantics RFC 9457 Problem Details RFC 9745 Deprecation Header RFC 8594 Sunset Header Google AIP-180 Backward Compatibility Google AIP-185 Versioning Google AIP-158 Pagination Google AIP-160 Filtering OpenAPI Specification