{
  "uid": "cogitave.learn.api-design.introduction",
  "kind": "moduleUnit",
  "href": "/modules/api-design/introduction/",
  "title": "Introduction",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "Why one shape, four protocols",
    "What you will get from this module"
  ],
  "source": "An API is a promise. Once a human, an agent, or another service depends on the\nshape of your surface, that shape is a contract you have to honor. Cogitave takes\ntwo questions that most teams blur together and gives each its own standard: how\na contract is **shaped**, and how a contract **changes over time**.\n\n- The [API design standard](../../../../standards/docs/standards/api-design.md)\n  owns the **shape** - resource modeling, naming, standard methods, the error\n  model, pagination, idempotency. It says what a good *v1* looks like.\n- The [versioning-and-deprecation standard](../../../../standards/docs/standards/api-versioning-and-deprecation.md)\n  owns the **evolution** - how that same contract is versioned, deprecated,\n  sunset, and retired. It says how a shape *changes* without breaking anyone.\n\nThe two are read together and deliberately never restate each other. The design\nstandard is settled by [ADR-0019](../../../../standards/docs/decisions/0019-api-design-and-design-system.md)\nand the versioning standard by [ADR-0015](../../../../standards/docs/decisions/0015-api-versioning-deprecation-and-product-core-baseline.md),\nwhich together fix the interface layer for the whole estate before the first\nsurface ships.\n\n> [!IMPORTANT]\n> **Day-0 honesty.** Most product cores are still being written. These standards\n> are the spec each surface conforms to **as it is authored**, enforced by\n> linters in CI and gated by the request lifecycle - not a description of shipped\n> APIs.\n\n## Why one shape, four protocols\n\nCogitave is MCP-native and also speaks HTTP, gRPC, and GraphQL. The design\nstandard's core bet is that a single concept has **one shape** across all four:\nsame field names, same enum values, same error taxonomy, same pagination\ncontract. That is what lets an agent or an auditor read one model instead of\nfour - and what stops an AI from re-deriving a surface that already exists.\n\n## What you will get from this module\n\nNot a REST-versus-gRPC debate - a working command of the conventions you apply to\ndesign a clean surface, the handful of MUST invariants you can never deviate\nfrom, and the discipline to evolve that surface additively so a live consumer is\nnever broken without consent.\n",
  "partOf": "cogitave.learn.api-design",
  "durationInMinutes": 4,
  "quiz": null
}