Update to Headcount: Technology

{
  "description": "Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking.",
  "included_files": [
    {
      "relative_path": "references/sources.md",
      "size_in_bytes": 2230
    }
  ],
  "name": "api-design",
  "skill_md_contents": "---\nname: api-design\ndescription: Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking.\n---\n\n# API design\n\nAn API is a promise you cannot withdraw once someone depends on it. Design accordingly: the cost of\ngetting it wrong is paid continuously by everyone who integrates.\n\n## Model the domain, not the database\n\nExpose concepts the consumer thinks in. An interface that mirrors internal table structure leaks\nimplementation, breaks whenever storage changes, and forces consumers to reconstruct meaning you\nalready had.\n\nName things as the domain names them. Consistency in naming, casing, date formats and identifier\nstyle matters more than any individual choice being optimal — an interface that is uniformly\nimperfect is learnable, and one that is inconsistently excellent is not.\n\n## Errors are part of the contract\n\nMost integrations spend most of their code on failure. Give it the same care as the success path:\n\n- **Distinguish machine-readable code from human-readable message.** Consumers branch on the code;\n  the message is for the developer reading logs.\n- **Say what to do about it.** Retryable or not, and after how long.\n- **Never leak internals** — stack traces and SQL in error bodies are a security finding as well as\n  bad design.\n- **Be consistent about which failures are which status.** Validation, authorization, and conflict\n  are different situations and should never share a shape.\n\n## Compatibility\n\nAdding an optional field is safe. Removing a field, renaming one, tightening validation, changing a\ndefault, or adding a required parameter are all breaking, and the last three break consumers who are\ndoing nothing wrong.\n\nVersion when you must break, and be explicit about how long the previous version lives. A\ndeprecation without a date is a deprecation nobody acts on.\n\nPrefer expansion over versioning where possible: a new optional field costs a consumer nothing, a new\nversion costs them a migration.\n\n## Pagination, filtering and limits\n\nAny collection that can grow needs pagination from the first release — retrofitting it is a breaking\nchange to every consumer. Prefer cursors over offsets for anything that changes while being read;\noffset pagination silently skips and duplicates records under concurrent writes.\n\nState rate limits in the contract and communicate them in responses. An undocumented limit is\ndiscovered in the consumer's production incident.\n\n## Sources\n\n`references/sources.md` in this skill lists the outside authorities that settle the questions\nhere — what each one is authoritative for, and what you may do with it. Check them before\nanswering on anything they cover, and cite what you used. Most are free to read and not free\nto reproduce; the use note on each is binding.\n\n## Tooling\n\nSpecification and documentation: OpenAPI with Redocly, Stoplight, or Scalar; gRPC with protocol\nbuffers where the consumers are internal services, and similar.\n\nDesign review and testing: Postman, Insomnia, Bruno, and similar. Contract testing — Pact and\nsimilar — is what catches a breaking change before a consumer does.\n\nGenerate the documentation from the specification and the specification from or alongside the code.\nHand-maintained API documentation is wrong within a release, and being confidently wrong is worse\nfor a consumer than being absent.\n\n## Never\n\n- Expose internal identifiers or storage structure through the interface.\n- Return errors whose meaning must be inferred from the message text.\n- Tighten validation on an existing endpoint and call it non-breaking.\n- Ship a collection endpoint without pagination.\n"
}