[
 {
  "id": "rest",
  "name": "REST",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Resource-oriented design where nouns are addressed by URLs and manipulated with a uniform set of HTTP methods.",
  "when": "You are exposing business entities to a broad, unknown set of consumers.",
  "watch": "Purist debates about \"true REST\" distract from consistency, which is what consumers actually need.",
  "example": "GET /customers/42",
  "refs": "Fielding dissertation (2000); RFC 9110",
  "apisio": []
 },
 {
  "id": "hypermedia-hateoas",
  "name": "Hypermedia (HATEOAS)",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Responses carry links and actions that tell the client what it can do next, so clients follow links instead of building URLs.",
  "when": "Workflows change often and you want clients to discover state transitions at runtime.",
  "watch": "Few client libraries consume hypermedia generically; most consumers hard-code URLs anyway.",
  "example": "\"_links\": {\"cancel\": {\"href\": \"/orders/7/cancel\"}}",
  "refs": "HAL, Siren, JSON:API, Hydra",
  "apisio": []
 },
 {
  "id": "rpc-over-http",
  "name": "RPC over HTTP",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Expose procedures (verbs) instead of resources, typically POSTing a method name and arguments.",
  "when": "The domain is action-heavy and does not map cleanly onto resources.",
  "watch": "Loses HTTP caching and method semantics; every call looks like a POST.",
  "example": "POST /rpc {\"method\":\"transfer\",\"params\":{...}}",
  "refs": "JSON-RPC 2.0, XML-RPC",
  "apisio": []
 },
 {
  "id": "json-rpc",
  "name": "JSON-RPC",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Common",
  "what": "A lightweight, transport-agnostic RPC envelope with id, method, params, and result/error.",
  "when": "You want simple RPC over HTTP, WebSocket, or raw TCP with batching built in.",
  "watch": "No schema or discovery story on its own; the MCP protocol now builds on it.",
  "example": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"sum\",\"params\":[1,2]}",
  "refs": "JSON-RPC 2.0 spec",
  "apisio": []
 },
 {
  "id": "grpc",
  "name": "gRPC",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Common",
  "what": "Contract-first RPC using Protocol Buffers over HTTP/2, supporting unary and streaming calls.",
  "when": "Internal service-to-service traffic where performance, typed contracts and streaming matter.",
  "watch": "Browsers need gRPC-Web or Connect, and the binary payloads are harder to debug by eye.",
  "example": "rpc GetOrder(GetOrderRequest) returns (Order);",
  "refs": "gRPC, Protocol Buffers",
  "apisio": []
 },
 {
  "id": "grpc-web-connect",
  "name": "gRPC-Web / Connect",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Browser- and HTTP/1.1-friendly variants of gRPC that keep protobuf contracts but work through ordinary proxies.",
  "when": "You want one protobuf contract serving both backend and browser clients.",
  "watch": "Client streaming support is limited in browsers.",
  "example": "POST /acme.v1.OrderService/GetOrder",
  "refs": "gRPC-Web, Connect protocol",
  "apisio": []
 },
 {
  "id": "graphql",
  "name": "GraphQL",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A typed schema with a query language that lets clients ask for exactly the fields they need in one round trip.",
  "when": "Many client types with different data needs over a connected graph of entities.",
  "watch": "HTTP caching is harder, query cost must be limited, and errors come back with 200 status codes.",
  "example": "query { order(id:7) { total customer { name } } }",
  "refs": "GraphQL spec, GraphQL over HTTP, apis.io GraphQL",
  "apisio": [
   [
    "GraphQL",
    "/graphqls/"
   ]
  ]
 },
 {
  "id": "graphql-federation",
  "name": "GraphQL Federation",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Compose many team-owned GraphQL subgraphs into a single supergraph behind a router.",
  "when": "Several teams own parts of one graph and need to ship independently.",
  "watch": "Adds a router tier and cross-team schema governance.",
  "example": "@key(fields: \"id\") on type Product",
  "refs": "Apollo Federation, GraphQL Composite Schemas WG",
  "apisio": []
 },
 {
  "id": "soap",
  "name": "SOAP",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "XML envelope protocol with a WSDL contract and the WS-* extensions for security and transactions.",
  "when": "Integrating with enterprise, government, or financial systems that already speak it.",
  "watch": "Verbose and heavyweight; a poor choice for new public APIs.",
  "example": "<soap:Envelope><soap:Body>...</soap:Body></soap:Envelope>",
  "refs": "SOAP 1.2, WSDL",
  "apisio": []
 },
 {
  "id": "odata",
  "name": "OData",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A REST convention with a standardized query language ($filter, $select, $expand) and metadata documents.",
  "when": "Data-centric APIs consumed by analytics and BI tooling.",
  "watch": "Lets clients compose expensive queries, and the URLs get unwieldy.",
  "example": "GET /Products?$filter=Price lt 10&$select=Name",
  "refs": "OASIS OData v4",
  "apisio": []
 },
 {
  "id": "backend-for-frontend-bff",
  "name": "Backend for Frontend (BFF)",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A dedicated API layer per client experience (web, mobile, partner) that tailors and aggregates downstream services.",
  "when": "Different clients need very different shapes and cadences.",
  "watch": "Duplicated logic across BFFs; ownership can drift.",
  "example": "/mobile-bff/home-feed",
  "refs": "Sam Newman, \"Backend for Frontend\"",
  "apisio": []
 },
 {
  "id": "api-gateway",
  "name": "API Gateway",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "A single entry point that handles routing, auth, rate limiting, transformation and observability for many backends.",
  "when": "You run more than a handful of APIs and want consistent policy enforcement.",
  "watch": "Becomes a bottleneck or a dumping ground for business logic.",
  "example": "Kong, Apigee, AWS API Gateway, Envoy",
  "refs": "Gateway API (Kubernetes)",
  "apisio": []
 },
 {
  "id": "api-composition-aggregation",
  "name": "API Composition / Aggregation",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "One endpoint calls several services and merges the results so clients make one call instead of many.",
  "when": "Chatty clients are paying latency for many sequential calls.",
  "watch": "Partial failures need a policy: fail the whole response or degrade.",
  "example": "GET /order-summary/7 (orders + shipping + billing)",
  "refs": "Microservices.io API Composition",
  "apisio": []
 },
 {
  "id": "fa-ade",
  "name": "Façade",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Common",
  "what": "A simplified, stable interface placed in front of a complex or legacy system.",
  "when": "Modernizing a legacy system without forcing consumers to change.",
  "watch": "The façade can leak legacy semantics if you only rename things.",
  "example": "/v2/accounts in front of a mainframe",
  "refs": "Gang of Four Facade",
  "apisio": []
 },
 {
  "id": "anti-corruption-layer",
  "name": "Anti-Corruption Layer",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "A translation layer that keeps a foreign model from leaking into your domain.",
  "when": "Integrating with a third-party or legacy API whose model you do not want to adopt.",
  "watch": "Extra mapping code to maintain.",
  "example": "Adapter mapping a vendor's \"Client\" into your \"Customer\"",
  "refs": "Domain-Driven Design (Evans)",
  "apisio": []
 },
 {
  "id": "strangler-fig",
  "name": "Strangler Fig",
  "category": "Architectural Styles",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Incrementally route endpoints from a legacy system to a new one behind the same interface.",
  "when": "Replacing a monolith or old API without a big-bang cutover.",
  "watch": "Running two systems for a long time.",
  "example": "Gateway routes /orders/* to the new service, everything else to legacy",
  "refs": "Martin Fowler, StranglerFigApplication",
  "apisio": []
 },
 {
  "id": "event-driven-api",
  "name": "Event-Driven API",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Common",
  "what": "Expose state changes as events that consumers subscribe to rather than poll for.",
  "when": "Consumers need to react to changes quickly and at scale.",
  "watch": "Ordering, delivery guarantees and replay need careful design.",
  "example": "order.created published to a topic",
  "refs": "AsyncAPI, CloudEvents",
  "apisio": []
 },
 {
  "id": "cqrs",
  "name": "CQRS",
  "category": "Architectural Styles",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Separate the write (command) model and API from the read (query) model and API.",
  "when": "Read and write workloads have very different shapes or scale.",
  "watch": "Eventual consistency between the two sides surprises consumers.",
  "example": "POST /commands/place-order; GET /views/order-summary/7",
  "refs": "Greg Young, Martin Fowler",
  "apisio": []
 },
 {
  "id": "collection-item-resources",
  "name": "Collection / Item Resources",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Plural collection URLs list and create; item URLs address one member by id.",
  "when": "Almost any CRUD-shaped domain.",
  "watch": "Inconsistent pluralization across an API erodes trust.",
  "example": "GET /orders, POST /orders, GET /orders/7",
  "refs": "Google AIP-121, Zalando guidelines",
  "apisio": []
 },
 {
  "id": "sub-resources-nesting",
  "name": "Sub-Resources / Nesting",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Express ownership by nesting child collections under a parent.",
  "when": "The child cannot exist without the parent.",
  "watch": "Deep nesting (more than two levels) makes URLs brittle.",
  "example": "GET /orders/7/items",
  "refs": "Google AIP-122",
  "apisio": []
 },
 {
  "id": "singleton-resource",
  "name": "Singleton Resource",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A resource with exactly one instance per parent or caller, addressed without an id.",
  "when": "Settings, profiles, the current user.",
  "watch": "It cannot be created or deleted the way a collection item can.",
  "example": "GET /me, PATCH /accounts/9/settings",
  "refs": "Google AIP-156",
  "apisio": []
 },
 {
  "id": "controller-action-resource",
  "name": "Controller / Action Resource",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Model an operation that does not fit CRUD as a verb sub-resource, invoked with POST.",
  "when": "State transitions such as cancel, approve, or refund.",
  "watch": "Overuse turns REST back into RPC.",
  "example": "POST /orders/7/cancel",
  "refs": "REST API Design Rulebook (Massé)",
  "apisio": []
 },
 {
  "id": "custom-methods",
  "name": "Custom Methods",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Colon-suffixed verbs on a resource or collection for non-standard operations.",
  "when": "You want explicit verbs without inventing sub-resources.",
  "watch": "Some routers and proxies mishandle colons in paths.",
  "example": "POST /orders/7:cancel",
  "refs": "Google AIP-136",
  "apisio": []
 },
 {
  "id": "lookup-by-alternate-key",
  "name": "Lookup by Alternate Key",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Address a resource by a natural or business key as well as its id.",
  "when": "Consumers know the email or SKU but not your internal id.",
  "watch": "Two URLs for the same thing complicates caching and canonical links.",
  "example": "GET /customers?email=a@b.com or /customers/by-email/a@b.com",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "search-endpoint",
  "name": "Search Endpoint",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A dedicated search resource, often POST, accepting a rich query body.",
  "when": "Queries are too complex or too long for a query string.",
  "watch": "POST search loses cacheability (HTTP QUERY addresses this).",
  "example": "POST /orders/search {\"status\":[\"open\"],\"total\":{\"gt\":100}}",
  "refs": "IETF HTTP QUERY method draft",
  "apisio": []
 },
 {
  "id": "http-query-method",
  "name": "HTTP QUERY Method",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "A safe, idempotent method that carries a request body, so searches can be cached and retried like GET.",
  "when": "Complex read queries that need a body without the semantics of POST.",
  "watch": "Still a draft; gateway and client support is thin.",
  "example": "QUERY /orders  Content-Type: application/json",
  "refs": "IETF draft-ietf-httpbis-safe-method-w-body",
  "apisio": []
 },
 {
  "id": "bulk-batch-operations",
  "name": "Bulk / Batch Operations",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Create, update or delete many resources in one request.",
  "when": "Imports, syncs, and anything that would otherwise take thousands of calls.",
  "watch": "Partial failure reporting and payload size limits.",
  "example": "POST /orders:batchCreate",
  "refs": "Google AIP-233/234/235",
  "apisio": []
 },
 {
  "id": "composite-request",
  "name": "Composite Request",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Send several dependent sub-requests in one envelope, referencing earlier results.",
  "when": "Mobile or low-bandwidth clients that need transactional multi-step writes.",
  "watch": "Complex to implement and to document.",
  "example": "Salesforce composite API, Microsoft Graph $batch",
  "refs": "OData $batch",
  "apisio": []
 },
 {
  "id": "long-running-operation-resource",
  "name": "Long-Running Operation Resource",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Return an operation resource that the client polls until the work is done.",
  "when": "Work that takes longer than a reasonable request timeout.",
  "watch": "Clients must implement polling and handle expiry.",
  "example": "POST /exports -> 202 {\"name\":\"operations/abc\"}",
  "refs": "Google AIP-151",
  "apisio": []
 },
 {
  "id": "polymorphic-resources",
  "name": "Polymorphic Resources",
  "category": "Resource Design",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "One endpoint returns several subtypes, distinguished by a discriminator field.",
  "when": "Payment methods, notifications and other naturally variant types.",
  "watch": "Code generators handle oneOf and discriminators unevenly.",
  "example": "{\"type\":\"card\", ...} vs {\"type\":\"bank_account\", ...}",
  "refs": "OpenAPI discriminator",
  "apisio": []
 },
 {
  "id": "resource-expansion",
  "name": "Resource Expansion",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Let clients ask for related objects to be embedded inline instead of returned as ids.",
  "when": "Clients routinely make follow-up calls to fetch related objects.",
  "watch": "Unbounded expansion creates expensive responses.",
  "example": "GET /charges/1?expand[]=customer",
  "refs": "Stripe expand, JSON:API include",
  "apisio": []
 },
 {
  "id": "sparse-fieldsets",
  "name": "Sparse Fieldsets",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Clients choose which fields come back.",
  "when": "Large resources and bandwidth-sensitive clients.",
  "watch": "Responses vary per request, which complicates caching.",
  "example": "GET /users/1?fields=name,email",
  "refs": "JSON:API sparse fieldsets, Google field masks",
  "apisio": []
 },
 {
  "id": "views-projections",
  "name": "Views / Projections",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Named response shapes (basic, full) instead of arbitrary field selection.",
  "when": "You want controlled payload sizes without open-ended selection.",
  "watch": "Only works if you pick a few views and stick to them.",
  "example": "GET /books/1?view=BASIC",
  "refs": "Google AIP-157",
  "apisio": []
 },
 {
  "id": "filtering",
  "name": "Filtering",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Narrow a collection by field values through query parameters or a filter expression.",
  "when": "Any collection that will grow.",
  "watch": "Ad-hoc filter syntaxes differ in every API.",
  "example": "GET /orders?status=open&created_after=2026-01-01",
  "refs": "Google AIP-160, OData $filter, RSQL",
  "apisio": []
 },
 {
  "id": "sorting",
  "name": "Sorting",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Let the client order results by one or more fields.",
  "when": "Lists that people browse.",
  "watch": "Sorting on unindexed fields hurts at scale.",
  "example": "GET /orders?sort=-created_at,total",
  "refs": "JSON:API sort",
  "apisio": []
 },
 {
  "id": "offset-pagination",
  "name": "Offset Pagination",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Page with offset and limit (or page and per_page).",
  "when": "Small or static datasets where jumping to page N matters.",
  "watch": "Slow on large tables, and it skips or duplicates rows as data changes.",
  "example": "GET /orders?offset=40&limit=20",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "cursor-pagination",
  "name": "Cursor Pagination",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Return an opaque cursor that points at the next page.",
  "when": "Large or fast-changing datasets and feeds.",
  "watch": "There is no random access to page N.",
  "example": "GET /orders?after=eyJpZCI6NDJ9",
  "refs": "Relay Cursor Connections, Google AIP-158",
  "apisio": []
 },
 {
  "id": "keyset-pagination",
  "name": "Keyset Pagination",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Paginate with a WHERE clause on the last seen sort key instead of an offset.",
  "when": "Very large tables that need stable, fast paging.",
  "watch": "Needs a unique, indexed sort key.",
  "example": "GET /events?since_id=9001",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "link-header-pagination",
  "name": "Link Header Pagination",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Advertise next, prev, first and last pages in the HTTP Link header.",
  "when": "You want pagination that stays out of the response body.",
  "watch": "Easy for clients to miss; some proxies strip headers.",
  "example": "Link: </orders?page=3>; rel=\"next\"",
  "refs": "RFC 8288 Web Linking",
  "apisio": []
 },
 {
  "id": "total-count",
  "name": "Total Count",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Report the total number of matching items alongside a page.",
  "when": "UIs need page counts or progress.",
  "watch": "Exact counts are expensive on large datasets, so consider estimates.",
  "example": "X-Total-Count: 1234",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "full-text-search-parameter",
  "name": "Full-Text Search Parameter",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A single q parameter for relevance-ranked text search.",
  "when": "Users type free text.",
  "watch": "Ranking is opaque to consumers.",
  "example": "GET /products?q=red+shoes",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "faceting-aggregations",
  "name": "Faceting / Aggregations",
  "category": "Query Patterns",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Return counts grouped by field values with the results.",
  "when": "Search UIs with filter sidebars, and analytics.",
  "watch": "Expensive to compute; cache the facet counts.",
  "example": "\"facets\": {\"color\": {\"red\": 12}}",
  "refs": "Elasticsearch aggregations",
  "apisio": []
 },
 {
  "id": "idempotency-keys",
  "name": "Idempotency Keys",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The client sends a unique key so the server can safely deduplicate retried POSTs.",
  "when": "Payments and anything else where a duplicate write is costly.",
  "watch": "Keys need storage, expiry and request-fingerprint matching.",
  "example": "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324",
  "refs": "IETF Idempotency-Key header draft, Stripe",
  "apisio": []
 },
 {
  "id": "idempotent-methods",
  "name": "Idempotent Methods",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "PUT and DELETE produce the same result however many times they are applied.",
  "when": "Designing writes that are safe to retry.",
  "watch": "Side effects such as emails break the guarantee.",
  "example": "PUT /users/1 (full replace)",
  "refs": "RFC 9110 §9.2.2",
  "apisio": []
 },
 {
  "id": "put-full-replace",
  "name": "PUT Full Replace",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Replace the whole resource representation.",
  "when": "Clients hold the full state.",
  "watch": "Missing fields get wiped, which surprises clients.",
  "example": "PUT /users/1 {full body}",
  "refs": "RFC 9110",
  "apisio": []
 },
 {
  "id": "json-merge-patch",
  "name": "JSON Merge Patch",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "PATCH with a partial document; null deletes a field.",
  "when": "Simple partial updates.",
  "watch": "You cannot set a value to null, and arrays are replaced wholesale.",
  "example": "PATCH Content-Type: application/merge-patch+json",
  "refs": "RFC 7396",
  "apisio": []
 },
 {
  "id": "json-patch",
  "name": "JSON Patch",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "PATCH with an ordered list of operations (add, remove, replace, move, test).",
  "when": "Precise array edits and conditional updates.",
  "watch": "Verbose, and hard for humans to write.",
  "example": "[{\"op\":\"replace\",\"path\":\"/name\",\"value\":\"x\"}]",
  "refs": "RFC 6902",
  "apisio": []
 },
 {
  "id": "field-masks",
  "name": "Field Masks",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "An explicit list of the fields an update touches.",
  "when": "Partial updates that need unambiguous semantics.",
  "watch": "One more parameter to keep in sync with the body.",
  "example": "PATCH /books/1?update_mask=title,author",
  "refs": "Google AIP-134",
  "apisio": []
 },
 {
  "id": "upsert",
  "name": "Upsert",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Create the resource if it is missing, update it if it exists, usually through PUT to a client-chosen id.",
  "when": "Syncing from systems that own their own ids.",
  "watch": "Typos silently create new records.",
  "example": "PUT /customers/ext-123",
  "refs": "Google AIP-134 allow_missing",
  "apisio": []
 },
 {
  "id": "optimistic-concurrency",
  "name": "Optimistic Concurrency",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Writes include the version the client last saw and are rejected if it changed.",
  "when": "Concurrent editors could overwrite each other (lost updates).",
  "watch": "Clients must handle 412 and retry or merge.",
  "example": "If-Match: \"v7\" -> 412 Precondition Failed",
  "refs": "RFC 9110 conditional requests, RFC 6585 428",
  "apisio": []
 },
 {
  "id": "soft-delete",
  "name": "Soft Delete",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Mark resources deleted and hide them instead of destroying them.",
  "when": "Undo, audits and legal retention.",
  "watch": "Uniqueness constraints and \"show deleted\" filters get tricky.",
  "example": "DELETE /docs/1 -> {\"state\":\"DELETED\"}",
  "refs": "Google AIP-164",
  "apisio": []
 },
 {
  "id": "undelete-restore",
  "name": "Undelete / Restore",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "An explicit operation to bring back a soft-deleted resource.",
  "when": "Deletes should be recoverable.",
  "watch": "Define how long a resource stays recoverable.",
  "example": "POST /docs/1:undelete",
  "refs": "Google AIP-164",
  "apisio": []
 },
 {
  "id": "partial-success-207",
  "name": "Partial Success (207)",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Report per-item results for a batch instead of a single status.",
  "when": "Bulk operations where some items fail.",
  "watch": "Clients treat the 2xx as total success unless they look inside.",
  "example": "207 Multi-Status with per-item statuses",
  "refs": "RFC 4918",
  "apisio": []
 },
 {
  "id": "client-generated-ids",
  "name": "Client-Generated IDs",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The client chooses the id at creation time.",
  "when": "Offline-first clients and idempotent creates.",
  "watch": "Collisions and enumeration need validation.",
  "example": "PUT /notes/{uuid}",
  "refs": "Google AIP-133",
  "apisio": []
 },
 {
  "id": "state-machine-transitions",
  "name": "State Machine Transitions",
  "category": "Write Semantics",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Model lifecycle states explicitly and only allow valid transitions.",
  "when": "Orders, tickets, approvals and other workflow-heavy domains.",
  "watch": "Clients need the state diagram, so document it.",
  "example": "POST /tickets/9/transitions {\"to\":\"resolved\"}",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "asynchronous-request-reply-202",
  "name": "Asynchronous Request-Reply (202)",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Accept work with 202 and a Location for a status resource the client polls.",
  "when": "Requests outlast HTTP timeouts.",
  "watch": "Polling cost, plus cleanup of finished status resources.",
  "example": "202 Accepted  Location: /jobs/55",
  "refs": "RFC 9110 202, Azure Architecture Center",
  "apisio": []
 },
 {
  "id": "polling",
  "name": "Polling",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "The client repeatedly asks for changes or status.",
  "when": "Simple integrations and firewalled consumers.",
  "watch": "Wasted calls and added latency; send Retry-After hints.",
  "example": "GET /jobs/55 every 5s",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "long-polling",
  "name": "Long Polling",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The server holds a request open until there is data or a timeout, then the client re-requests.",
  "when": "Near-real-time updates without WebSocket infrastructure.",
  "watch": "Ties up connections, and proxies may cut long requests.",
  "example": "GET /updates?wait=30",
  "refs": "Bayeux/Comet heritage",
  "apisio": []
 },
 {
  "id": "webhooks",
  "name": "Webhooks",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "The provider POSTs an event to a URL the consumer registered.",
  "when": "Consumers need push notifications of changes.",
  "watch": "Delivery retries, ordering, security and consumer downtime.",
  "example": "POST https://consumer.example/hooks {\"type\":\"invoice.paid\"}",
  "refs": "Standard Webhooks, CloudEvents",
  "apisio": []
 },
 {
  "id": "signed-webhooks",
  "name": "Signed Webhooks",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Sign webhook payloads (HMAC or asymmetric) so consumers can verify their origin.",
  "when": "Always, whenever you send webhooks.",
  "watch": "Clock skew and replay; include timestamps.",
  "example": "webhook-signature: v1,abc...",
  "refs": "Standard Webhooks spec, RFC 9421",
  "apisio": []
 },
 {
  "id": "webhook-subscription-management",
  "name": "Webhook Subscription Management",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "An API to create, list, test and delete webhook subscriptions.",
  "when": "Consumers integrate programmatically at scale.",
  "watch": "Validate the endpoint first (challenge-response).",
  "example": "POST /webhook-endpoints",
  "refs": "REST Hooks, WebSub",
  "apisio": []
 },
 {
  "id": "thin-events-fetch-back",
  "name": "Thin Events / Fetch-Back",
  "category": "Asynchronous",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Events carry only ids and the consumer fetches the current state.",
  "when": "Payloads are sensitive or out-of-order delivery is common.",
  "watch": "Doubles the call volume.",
  "example": "{\"type\":\"order.updated\",\"id\":\"7\"} then GET /orders/7",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "event-carried-state-transfer",
  "name": "Event-Carried State Transfer",
  "category": "Asynchronous",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Events carry the full changed state so consumers never call back.",
  "when": "Decoupled consumers that keep their own copies.",
  "watch": "Large payloads and schema evolution.",
  "example": "{\"type\":\"order.updated\",\"data\":{...full order...}}",
  "refs": "Martin Fowler",
  "apisio": []
 },
 {
  "id": "callbacks",
  "name": "Callbacks",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The request includes a URL where the result will be POSTed when ready.",
  "when": "A one-off async result for a single request.",
  "watch": "Same delivery problems as webhooks.",
  "example": "POST /payments {\"callback_url\":\"https://...\"}",
  "refs": "OpenAPI callbacks",
  "apisio": []
 },
 {
  "id": "server-sent-events-sse",
  "name": "Server-Sent Events (SSE)",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A one-way server-to-client stream of text events over a plain HTTP response.",
  "when": "Live feeds, progress and LLM token streaming.",
  "watch": "One direction only; connection limits apply on HTTP/1.1.",
  "example": "Content-Type: text/event-stream  data: {...}",
  "refs": "WHATWG HTML Living Standard",
  "apisio": []
 },
 {
  "id": "websockets",
  "name": "WebSockets",
  "category": "Asynchronous",
  "transport": "Both",
  "maturity": "Common",
  "what": "A full-duplex, message-oriented connection upgraded from HTTP and running over TCP.",
  "when": "Chat, collaboration, trading and games.",
  "watch": "Stateful connections complicate scaling, auth refresh and load balancing.",
  "example": "GET /ws  Upgrade: websocket",
  "refs": "RFC 6455, RFC 8441",
  "apisio": []
 },
 {
  "id": "http-streaming-ndjson",
  "name": "HTTP Streaming / NDJSON",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Stream a large or unbounded response as newline-delimited records.",
  "when": "Exports, logs and LLM outputs.",
  "watch": "Errors that happen mid-stream need an in-band signal.",
  "example": "Content-Type: application/x-ndjson",
  "refs": "NDJSON, JSON Lines",
  "apisio": []
 },
 {
  "id": "websub",
  "name": "WebSub",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Hub-based publish/subscribe for web content using webhooks.",
  "when": "Feeds and content distribution.",
  "watch": "Few new adopters.",
  "example": "Link: <https://hub>; rel=\"hub\"",
  "refs": "W3C WebSub",
  "apisio": []
 },
 {
  "id": "streamable-http-mcp",
  "name": "Streamable HTTP (MCP)",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "A single endpoint that answers JSON-RPC POSTs with JSON or upgrades the response to an SSE stream.",
  "when": "Agent tool servers that need both request-response and streaming.",
  "watch": "Session management and resumability are still settling.",
  "example": "POST /mcp  Accept: application/json, text/event-stream",
  "refs": "Model Context Protocol",
  "apisio": []
 },
 {
  "id": "webhook-retry-with-backoff",
  "name": "Webhook Retry with Backoff",
  "category": "Asynchronous",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Retry failed deliveries on an increasing schedule, then dead-letter them.",
  "when": "Consumers will be down sometimes.",
  "watch": "Duplicate deliveries mean consumers must be idempotent.",
  "example": "retry at 1m, 5m, 30m, 2h, 12h",
  "refs": "Standard Webhooks",
  "apisio": []
 },
 {
  "id": "event-replay-redelivery",
  "name": "Event Replay / Redelivery",
  "category": "Asynchronous",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Let consumers re-fetch or replay missed events from a log or an events endpoint.",
  "when": "Consumers recover from outages.",
  "watch": "Requires retention and cursors.",
  "example": "GET /events?since=evt_123",
  "refs": "Stripe Events API, Kafka offsets",
  "apisio": []
 },
 {
  "id": "content-negotiation",
  "name": "Content Negotiation",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "The client states preferred formats and the server picks one.",
  "when": "Several representations of the same resource (JSON, CSV, XML).",
  "watch": "Vary headers are needed for correct caching.",
  "example": "Accept: text/csv",
  "refs": "RFC 9110 §12",
  "apisio": []
 },
 {
  "id": "media-type-design",
  "name": "Media Type Design",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Define custom or profiled media types that carry semantics and version.",
  "when": "Hypermedia, or versioning through media types.",
  "watch": "Tooling rarely understands custom types.",
  "example": "application/vnd.acme.order+json; version=2",
  "refs": "RFC 6838, RFC 6906 profile",
  "apisio": []
 },
 {
  "id": "envelope-vs-bare-responses",
  "name": "Envelope vs Bare Responses",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Wrap payloads in a data/meta/links envelope, or return the resource directly.",
  "when": "Envelopes help with pagination metadata; bare bodies are simpler.",
  "watch": "Mixing the two styles in one API.",
  "example": "{\"data\":[...],\"meta\":{\"next\":\"...\"}}",
  "refs": "JSON:API",
  "apisio": []
 },
 {
  "id": "problem-details",
  "name": "Problem Details",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "A standard JSON error format with type, title, status, detail and instance.",
  "when": "Every HTTP API.",
  "watch": "Teams invent their own extensions inconsistently.",
  "example": "application/problem+json {\"type\":\"...\",\"title\":\"Out of credit\"}",
  "refs": "RFC 9457",
  "apisio": []
 },
 {
  "id": "consistent-error-codes",
  "name": "Consistent Error Codes",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Stable, machine-readable error codes alongside human messages.",
  "when": "Clients branch on specific failures.",
  "watch": "Codes multiply without a registry.",
  "example": "{\"code\":\"card_declined\"}",
  "refs": "Google AIP-193",
  "apisio": []
 },
 {
  "id": "status-code-semantics",
  "name": "Status Code Semantics",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Use the right status class and code (201, 204, 400, 404, 409, 422, 429, 503).",
  "when": "Always.",
  "watch": "Returning 200 with an error body defeats tooling.",
  "example": "201 Created + Location header",
  "refs": "RFC 9110 §15",
  "apisio": []
 },
 {
  "id": "standard-date-money-locale-formats",
  "name": "Standard Date / Money / Locale Formats",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "ISO 8601 timestamps, ISO 4217 currencies, minor-unit integers, and BCP 47 languages.",
  "when": "Any API with times, money or text.",
  "watch": "Floats for money; local times without an offset.",
  "example": "{\"amount\":1999,\"currency\":\"USD\",\"at\":\"2026-11-19T10:00:00Z\"}",
  "refs": "RFC 3339, ISO 4217, BCP 47",
  "apisio": []
 },
 {
  "id": "enumerations-with-unknowns",
  "name": "Enumerations with Unknowns",
  "category": "Representation",
  "transport": "Both",
  "maturity": "Common",
  "what": "Treat enums as open: clients must tolerate values they have not seen.",
  "when": "Enums will grow.",
  "watch": "Strict generated clients crash on new values.",
  "example": "\"status\": \"partially_refunded\"",
  "refs": "Zalando x-extensible-enum",
  "apisio": []
 },
 {
  "id": "null-vs-absent",
  "name": "Null vs Absent",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Define clearly whether a missing field and a null field mean different things.",
  "when": "Partial responses and PATCH.",
  "watch": "Ambiguity causes accidental data wipes.",
  "example": "{\"middle_name\": null}",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "opaque-identifiers",
  "name": "Opaque Identifiers",
  "category": "Representation",
  "transport": "Both",
  "maturity": "Common",
  "what": "Ids are strings with no meaning clients should parse, often type-prefixed.",
  "when": "Always; it keeps you free to change storage.",
  "watch": "Clients still parse them if you leak structure.",
  "example": "\"id\": \"cus_9s6XKzkNRiz8i3\"",
  "refs": "Stripe object ids, TypeID",
  "apisio": []
 },
 {
  "id": "hypermedia-links-in-payloads",
  "name": "Hypermedia Links in Payloads",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Include self and related links in responses.",
  "when": "You want discoverability and fewer client-built URLs.",
  "watch": "Payload bloat if the links are not used.",
  "example": "\"links\": {\"self\":\"/orders/7\"}",
  "refs": "RFC 8288, HAL, JSON:API",
  "apisio": []
 },
 {
  "id": "localization",
  "name": "Localization",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Return translated content based on Accept-Language.",
  "when": "Global consumer-facing content.",
  "watch": "Caching needs Vary: Accept-Language.",
  "example": "Accept-Language: es-MX",
  "refs": "RFC 9110 §12.5.4",
  "apisio": []
 },
 {
  "id": "binary-file-upload-multipart",
  "name": "Binary / File Upload (Multipart)",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Send files and metadata together in a multipart/form-data request.",
  "when": "Small to medium uploads.",
  "watch": "Memory pressure on large files.",
  "example": "Content-Type: multipart/form-data",
  "refs": "RFC 7578",
  "apisio": []
 },
 {
  "id": "presigned-direct-upload-urls",
  "name": "Presigned / Direct Upload URLs",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The API returns a short-lived URL so clients upload straight to object storage.",
  "when": "Large files that should not pass through your servers.",
  "watch": "Expiry and validation happen out of band.",
  "example": "POST /uploads -> {\"url\":\"https://s3...X-Amz-Signature=...\"}",
  "refs": "AWS S3 presigned URLs",
  "apisio": []
 },
 {
  "id": "resumable-uploads",
  "name": "Resumable Uploads",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Upload in chunks that can resume after interruption.",
  "when": "Large files on unreliable networks.",
  "watch": "Server-side state for incomplete uploads.",
  "example": "PATCH /files/abc  Upload-Offset: 1048576",
  "refs": "tus.io, IETF resumable uploads draft",
  "apisio": []
 },
 {
  "id": "range-requests",
  "name": "Range Requests",
  "category": "Representation",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Fetch part of a resource by byte range.",
  "when": "Media streaming and resumable downloads.",
  "watch": "Rarely implemented on dynamic resources.",
  "example": "Range: bytes=0-1023 -> 206",
  "refs": "RFC 9110 §14",
  "apisio": []
 },
 {
  "id": "uri-versioning",
  "name": "URI Versioning",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Put the major version in the path.",
  "when": "Public APIs that need simple, visible versioning.",
  "watch": "Every version is a new API to maintain.",
  "example": "/v1/orders",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "header-media-type-versioning",
  "name": "Header / Media Type Versioning",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Select the version with a header or an Accept parameter.",
  "when": "You want stable URLs for resources.",
  "watch": "Harder to test in a browser, and easy to forget.",
  "example": "Accept: application/vnd.acme+json;version=2",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "date-based-versioning",
  "name": "Date-Based Versioning",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Pin each consumer to the API as it was on a date, with server-side transforms.",
  "when": "Many small, frequent changes without breaking anyone.",
  "watch": "The transform layer is real engineering.",
  "example": "Stripe-Version: 2026-10-28",
  "refs": "Stripe API versioning",
  "apisio": []
 },
 {
  "id": "query-parameter-versioning",
  "name": "Query Parameter Versioning",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The version is chosen through a query parameter.",
  "when": "Simple opt-in to new behavior.",
  "watch": "Pollutes cache keys and is easy to omit.",
  "example": "?api-version=2026-05-01",
  "refs": "Azure REST API guidelines",
  "apisio": []
 },
 {
  "id": "additive-only-change",
  "name": "Additive-Only Change",
  "category": "Versioning & Evolution",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Evolve by adding fields and endpoints, never removing or repurposing them.",
  "when": "Avoiding version bumps.",
  "watch": "Accumulated cruft.",
  "example": "Add \"middle_name\"; never rename \"name\"",
  "refs": "Postel's law, Zalando guidelines",
  "apisio": []
 },
 {
  "id": "tolerant-reader",
  "name": "Tolerant Reader",
  "category": "Versioning & Evolution",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Clients ignore unknown fields and depend only on what they need.",
  "when": "All clients, always.",
  "watch": "Strict deserializers break it.",
  "example": "Ignore unknown JSON properties",
  "refs": "Martin Fowler TolerantReader",
  "apisio": []
 },
 {
  "id": "deprecation-header",
  "name": "Deprecation Header",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Signal in responses that an endpoint is deprecated.",
  "when": "Retiring operations.",
  "watch": "Nobody reads headers unless tools surface them.",
  "example": "Deprecation: @1767225600",
  "refs": "RFC 9745, apis.io Deprecation",
  "apisio": [
   [
    "Deprecation",
    "/deprecation/"
   ]
  ]
 },
 {
  "id": "sunset-header",
  "name": "Sunset Header",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Announce when an endpoint will stop working.",
  "when": "Planned removals.",
  "watch": "You have to actually honor the date.",
  "example": "Sunset: Wed, 01 Jul 2027 00:00:00 GMT",
  "refs": "RFC 8594, apis.io Deprecation",
  "apisio": [
   [
    "Deprecation",
    "/deprecation/"
   ]
  ]
 },
 {
  "id": "consumer-driven-contracts",
  "name": "Consumer-Driven Contracts",
  "category": "Versioning & Evolution",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Consumers publish their expectations as tests the provider runs.",
  "when": "Many internal consumers of an evolving API.",
  "watch": "Contract tests are extra infrastructure.",
  "example": "Pact contract files verified in provider CI",
  "refs": "Pact",
  "apisio": []
 },
 {
  "id": "feature-flags-previews",
  "name": "Feature Flags / Previews",
  "category": "Versioning & Evolution",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Opt-in headers or flags for beta behavior.",
  "when": "Previewing changes with willing consumers.",
  "watch": "Previews that never graduate.",
  "example": "Accept: application/vnd.github.preview+json",
  "refs": "GitHub API previews",
  "apisio": []
 },
 {
  "id": "expand-contract-migration",
  "name": "Expand / Contract Migration",
  "category": "Versioning & Evolution",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Add the new shape, migrate consumers, then remove the old one.",
  "when": "Breaking changes in schemas or databases.",
  "watch": "It takes discipline to finish the contract step.",
  "example": "Ship new_field, dual-write, drop old_field",
  "refs": "Parallel change (Fowler)",
  "apisio": []
 },
 {
  "id": "api-keys",
  "name": "API Keys",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "A static secret identifying the calling application.",
  "when": "Simple server-to-server identification.",
  "watch": "Not user identity; leaked keys are common.",
  "example": "Authorization: Bearer sk_live_...",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "oauth-2-x-authorization-code-pkce",
  "name": "OAuth 2.x Authorization Code + PKCE",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Delegated user authorization through a browser redirect.",
  "when": "Third-party apps acting on behalf of users.",
  "watch": "Complex for beginners; requires redirect handling.",
  "example": "/authorize?response_type=code&code_challenge=...",
  "refs": "RFC 6749, RFC 7636, OAuth 2.1 draft, apis.io Security",
  "apisio": [
   [
    "Security",
    "/security/"
   ]
  ]
 },
 {
  "id": "oauth-client-credentials",
  "name": "OAuth Client Credentials",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Machine-to-machine tokens without a user.",
  "when": "Backend services and daemons.",
  "watch": "Over-broad scopes.",
  "example": "POST /token grant_type=client_credentials",
  "refs": "RFC 6749 §4.4",
  "apisio": []
 },
 {
  "id": "device-authorization-grant",
  "name": "Device Authorization Grant",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Users authorize on another device with a code.",
  "when": "TVs, CLIs and input-constrained devices.",
  "watch": "Polling the token endpoint.",
  "example": "\"Visit example.com/device and enter ABCD-1234\"",
  "refs": "RFC 8628",
  "apisio": []
 },
 {
  "id": "token-exchange",
  "name": "Token Exchange",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Swap one token for another with a different audience or scope.",
  "when": "Service chains, delegation and agents.",
  "watch": "Tracking who acted on behalf of whom.",
  "example": "grant_type=urn:ietf:params:oauth:grant-type:token-exchange",
  "refs": "RFC 8693",
  "apisio": []
 },
 {
  "id": "openid-connect",
  "name": "OpenID Connect",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "An identity layer on OAuth that returns an ID token about the user.",
  "when": "Sign-in and federated identity.",
  "watch": "Do not use ID tokens as API access tokens.",
  "example": "scope=openid profile email",
  "refs": "OpenID Connect Core",
  "apisio": []
 },
 {
  "id": "jwt-bearer-tokens",
  "name": "JWT Bearer Tokens",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Self-contained signed tokens validated without a lookup.",
  "when": "Stateless validation at scale.",
  "watch": "Revocation is hard, so keep them short-lived.",
  "example": "Authorization: Bearer eyJhbGciOi...",
  "refs": "RFC 7519, RFC 9068",
  "apisio": []
 },
 {
  "id": "scopes-and-fine-grained-permissions",
  "name": "Scopes and Fine-Grained Permissions",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Tokens carry narrow scopes or rich authorization details.",
  "when": "Least privilege for apps and agents.",
  "watch": "Scope explosion.",
  "example": "scope=orders:read",
  "refs": "RFC 9396 Rich Authorization Requests, apis.io Scopes",
  "apisio": [
   [
    "Scopes",
    "/scopes/"
   ]
  ]
 },
 {
  "id": "mtls",
  "name": "mTLS",
  "category": "Security & Access",
  "transport": "Both",
  "maturity": "Common",
  "what": "Both client and server present certificates.",
  "when": "Zero-trust service meshes and financial APIs.",
  "watch": "Certificate lifecycle operations.",
  "example": "Client cert bound to the access token",
  "refs": "RFC 8705, apis.io Security",
  "apisio": [
   [
    "Security",
    "/security/"
   ]
  ]
 },
 {
  "id": "hmac-request-signing",
  "name": "HMAC Request Signing",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Sign the request (method, path, body, timestamp) with a shared secret.",
  "when": "Tamper-proof requests without TLS termination trust.",
  "watch": "Canonicalization bugs.",
  "example": "AWS SigV4",
  "refs": "AWS Signature Version 4",
  "apisio": []
 },
 {
  "id": "http-message-signatures",
  "name": "HTTP Message Signatures",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "A standard for signing selected HTTP message components.",
  "when": "Interoperable request and response signing, including agent identity.",
  "watch": "Young ecosystem.",
  "example": "Signature-Input: sig1=(\"@method\" \"@path\");...",
  "refs": "RFC 9421",
  "apisio": []
 },
 {
  "id": "dpop",
  "name": "DPoP",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Sender-constrained tokens bound to a client key so stolen tokens are useless.",
  "when": "Public clients where token theft is a risk.",
  "watch": "Extra proof JWT on every call.",
  "example": "DPoP: eyJ0eXAiOiJkcG9wK2p3dCJ9...",
  "refs": "RFC 9449",
  "apisio": []
 },
 {
  "id": "cors",
  "name": "CORS",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Browser rules for which origins may call your API.",
  "when": "Any API called from browser JavaScript.",
  "watch": "A wildcard origin combined with credentials.",
  "example": "Access-Control-Allow-Origin: https://app.example",
  "refs": "WHATWG Fetch",
  "apisio": []
 },
 {
  "id": "multi-tenancy-addressing",
  "name": "Multi-Tenancy Addressing",
  "category": "Security & Access",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Identify the tenant by subdomain, path, header or token claim.",
  "when": "SaaS platforms.",
  "watch": "Per-tenant hosts break discovery.",
  "example": "https://{tenant}.api.example.com",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "rate-limiting",
  "name": "Rate Limiting",
  "category": "Traffic Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Cap requests per client per window and reject the excess with 429.",
  "when": "Any public API.",
  "watch": "Opaque limits frustrate developers, so publish them.",
  "example": "429 Too Many Requests  Retry-After: 30",
  "refs": "RFC 6585, IETF RateLimit headers draft, apis.io Rate Limits",
  "apisio": [
   [
    "Rate Limits",
    "/rate-limits/"
   ]
  ]
 },
 {
  "id": "ratelimit-headers",
  "name": "RateLimit Headers",
  "category": "Traffic Management",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Tell clients their quota and what remains on every response.",
  "when": "Well-behaved clients that throttle themselves.",
  "watch": "Header names vary across providers until the draft settles.",
  "example": "RateLimit: limit=100, remaining=40, reset=30",
  "refs": "IETF draft-ietf-httpapi-ratelimit-headers, apis.io Rate Limits",
  "apisio": [
   [
    "Rate Limits",
    "/rate-limits/"
   ]
  ]
 },
 {
  "id": "quotas-and-usage-plans",
  "name": "Quotas and Usage Plans",
  "category": "Traffic Management",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Daily or monthly allowances tied to a plan or tier.",
  "when": "Monetized and freemium APIs.",
  "watch": "Hard cut-offs mid-month anger customers.",
  "example": "10,000 calls/month on Free",
  "refs": "API gateway usage plans, apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "token-bucket-leaky-bucket",
  "name": "Token Bucket / Leaky Bucket",
  "category": "Traffic Management",
  "transport": "Both",
  "maturity": "Common",
  "what": "Algorithms that allow bursts while enforcing an average rate.",
  "when": "Smoothing traffic.",
  "watch": "Distributed counters across nodes.",
  "example": "Bucket of 100 refilling 10/s",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "retry-after",
  "name": "Retry-After",
  "category": "Traffic Management",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Tell clients when to try again after a 429 or 503.",
  "when": "Throttling and maintenance.",
  "watch": "Clients that ignore it.",
  "example": "Retry-After: 120",
  "refs": "RFC 9110 §10.2.3",
  "apisio": []
 },
 {
  "id": "load-shedding",
  "name": "Load Shedding",
  "category": "Traffic Management",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Deliberately reject low-priority work under overload.",
  "when": "Protecting core paths during spikes.",
  "watch": "Choosing what to shed.",
  "example": "503 for analytics calls during peak",
  "refs": "Google SRE book",
  "apisio": []
 },
 {
  "id": "priority-queues-fair-queuing",
  "name": "Priority Queues / Fair Queuing",
  "category": "Traffic Management",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Isolate tenants or request classes so one cannot starve the others.",
  "when": "Multi-tenant platforms.",
  "watch": "Configuration complexity.",
  "example": "Per-tenant concurrency limits",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "http-caching-cache-control",
  "name": "HTTP Caching (Cache-Control)",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Tell clients and CDNs how long a response is fresh.",
  "when": "Read-heavy, cacheable resources.",
  "watch": "Caching personalized data publicly.",
  "example": "Cache-Control: public, max-age=300",
  "refs": "RFC 9111",
  "apisio": []
 },
 {
  "id": "etag-conditional-get",
  "name": "ETag / Conditional GET",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Validators let clients revalidate and receive 304 Not Modified.",
  "when": "Saving bandwidth on unchanged data.",
  "watch": "Weak vs strong ETag semantics.",
  "example": "If-None-Match: \"abc\" -> 304",
  "refs": "RFC 9110 §8.8",
  "apisio": []
 },
 {
  "id": "stale-while-revalidate",
  "name": "stale-while-revalidate",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Serve stale content while refreshing in the background.",
  "when": "Latency-sensitive reads.",
  "watch": "Consumers briefly see old data.",
  "example": "Cache-Control: max-age=60, stale-while-revalidate=300",
  "refs": "RFC 5861",
  "apisio": []
 },
 {
  "id": "cdn-edge-apis",
  "name": "CDN / Edge APIs",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Serve or compute API responses at edge locations.",
  "when": "Global audiences and static catalog data.",
  "watch": "Invalidation and consistency.",
  "example": "Cloudflare Workers, CloudFront",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "compression",
  "name": "Compression",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "gzip, br or zstd response bodies.",
  "when": "JSON payloads over a few KB.",
  "watch": "CPU cost; BREACH with secrets in the body.",
  "example": "Content-Encoding: br",
  "refs": "RFC 9110, RFC 8878",
  "apisio": []
 },
 {
  "id": "http-2-multiplexing",
  "name": "HTTP/2 Multiplexing",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Many concurrent streams over one TCP connection.",
  "when": "Chatty clients and gRPC.",
  "watch": "TCP head-of-line blocking still applies.",
  "example": "One connection, 100 streams",
  "refs": "RFC 9113",
  "apisio": []
 },
 {
  "id": "http-3-quic",
  "name": "HTTP/3 / QUIC",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "HTTP over QUIC (UDP), with independent streams and 0-RTT resumption.",
  "when": "Mobile and lossy networks.",
  "watch": "UDP blocked on some enterprise networks.",
  "example": "Alt-Svc: h3=\":443\"",
  "refs": "RFC 9114, RFC 9000",
  "apisio": []
 },
 {
  "id": "request-coalescing",
  "name": "Request Coalescing",
  "category": "Caching & Performance",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Collapse identical in-flight requests into one backend call.",
  "when": "Hot keys and cache stampedes.",
  "watch": "Adds latency to the first request.",
  "example": "Varnish/Nginx proxy_cache_lock",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "prefer-header",
  "name": "Prefer Header",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Clients state preferences such as return=minimal or respond-async.",
  "when": "Letting clients trade payload size or sync behavior.",
  "watch": "Servers may ignore it; signal with Preference-Applied.",
  "example": "Prefer: return=minimal",
  "refs": "RFC 7240",
  "apisio": []
 },
 {
  "id": "delta-changes-feed",
  "name": "Delta / Changes Feed",
  "category": "Caching & Performance",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Return only what changed since a token.",
  "when": "Sync clients and offline apps.",
  "watch": "Token expiry and full-resync fallback.",
  "example": "GET /changes?since=tok_88",
  "refs": "Microsoft Graph delta query",
  "apisio": []
 },
 {
  "id": "retries-with-backoff-and-jitter",
  "name": "Retries with Backoff and Jitter",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Retry transient failures with exponentially growing, randomized delays.",
  "when": "Every client of every network API.",
  "watch": "Retrying non-idempotent calls without idempotency keys.",
  "example": "sleep(random(0, base * 2^n))",
  "refs": "AWS Architecture Blog",
  "apisio": []
 },
 {
  "id": "timeouts-and-deadlines",
  "name": "Timeouts and Deadlines",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Every call has a time budget, propagated downstream.",
  "when": "Always.",
  "watch": "Missing timeouts cause cascading hangs.",
  "example": "grpc-timeout: 2S",
  "refs": "gRPC deadlines",
  "apisio": []
 },
 {
  "id": "circuit-breaker",
  "name": "Circuit Breaker",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Common",
  "what": "Stop calling a failing dependency for a while and fail fast.",
  "when": "Protecting callers from slow or dead services.",
  "watch": "Tuning thresholds.",
  "example": "Open after 50% failures in 10s",
  "refs": "Michael Nygard, Release It!",
  "apisio": []
 },
 {
  "id": "bulkhead",
  "name": "Bulkhead",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Common",
  "what": "Isolate resources so one failing dependency cannot exhaust them all.",
  "when": "Services that depend on many backends.",
  "watch": "Underused pools.",
  "example": "Separate thread pools per dependency",
  "refs": "Release It!",
  "apisio": []
 },
 {
  "id": "fallback-graceful-degradation",
  "name": "Fallback / Graceful Degradation",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Common",
  "what": "Return cached, default or partial data when a dependency fails.",
  "when": "Non-critical data in a response.",
  "watch": "Silent degradation hides outages.",
  "example": "Recommendations empty instead of 500",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "hedged-requests",
  "name": "Hedged Requests",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Send a duplicate request after a delay and take whichever answers first.",
  "when": "Tail-latency-sensitive reads.",
  "watch": "Extra load; only for idempotent reads.",
  "example": "Backup request after the p95 delay",
  "refs": "Dean & Barroso, \"The Tail at Scale\"",
  "apisio": []
 },
 {
  "id": "health-check-endpoints",
  "name": "Health Check Endpoints",
  "category": "Resilience",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Liveness and readiness endpoints for orchestrators and monitors.",
  "when": "Anything deployed behind a load balancer.",
  "watch": "Deep checks that cascade failures.",
  "example": "GET /health -> {\"status\":\"pass\"}",
  "refs": "IETF Health Check Response Format draft",
  "apisio": []
 },
 {
  "id": "correlation-trace-ids",
  "name": "Correlation / Trace IDs",
  "category": "Observability",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Propagate a request id through every hop for debugging and tracing.",
  "when": "Distributed systems.",
  "watch": "Not echoing the id back to the client.",
  "example": "traceparent: 00-4bf9...-01",
  "refs": "W3C Trace Context",
  "apisio": []
 },
 {
  "id": "request-ids-in-responses",
  "name": "Request IDs in Responses",
  "category": "Observability",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Return a unique id clients can quote to support.",
  "when": "Every API.",
  "watch": "Logs not indexed by the id.",
  "example": "X-Request-Id: req_8xY2",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "structured-audit-logs",
  "name": "Structured Audit Logs",
  "category": "Observability",
  "transport": "Both",
  "maturity": "Common",
  "what": "Record who did what and when, as data consumers can query.",
  "when": "Regulated and enterprise APIs.",
  "watch": "Logging PII.",
  "example": "GET /audit-events",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "usage-analytics-api",
  "name": "Usage / Analytics API",
  "category": "Observability",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Expose consumers' own usage, errors and latency to them.",
  "when": "Self-serve developer experience.",
  "watch": "Data freshness.",
  "example": "GET /usage?month=2026-11",
  "refs": "Common practice, apis.io FinOps",
  "apisio": [
   [
    "FinOps",
    "/finops/"
   ]
  ]
 },
 {
  "id": "status-page-incident-api",
  "name": "Status Page / Incident API",
  "category": "Observability",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A machine-readable service status.",
  "when": "Consumers automate around your outages.",
  "watch": "Keeping it honest.",
  "example": "GET /api/v2/status.json",
  "refs": "Atlassian Statuspage API",
  "apisio": []
 },
 {
  "id": "openapi-description",
  "name": "OpenAPI Description",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "A machine-readable contract for an HTTP API.",
  "when": "Every HTTP API, for docs, SDKs, testing, governance and agents.",
  "watch": "Contracts that drift from the implementation.",
  "example": "openapi: 3.2.0",
  "refs": "OpenAPI Specification",
  "apisio": []
 },
 {
  "id": "asyncapi-description",
  "name": "AsyncAPI Description",
  "category": "Discovery & Contracts",
  "transport": "Both",
  "maturity": "Common",
  "what": "A machine-readable contract for event-driven and message APIs.",
  "when": "Kafka, MQTT, WebSocket and webhook APIs.",
  "watch": "Less tooling than OpenAPI.",
  "example": "asyncapi: 3.0.0",
  "refs": "AsyncAPI Specification, apis.io AsyncAPI",
  "apisio": [
   [
    "AsyncAPI",
    "/asyncapis/"
   ]
  ]
 },
 {
  "id": "arazzo-workflows",
  "name": "Arazzo Workflows",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Describe multi-step sequences of API calls and their dependencies.",
  "when": "Documenting real use cases and powering agents.",
  "watch": "Young tooling.",
  "example": "workflows: - workflowId: checkout",
  "refs": "Arazzo Specification, apis.io Arazzo",
  "apisio": [
   [
    "Arazzo",
    "/arazzos/"
   ]
  ]
 },
 {
  "id": "overlays",
  "name": "Overlays",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Apply repeatable changes to an OpenAPI document without editing the source.",
  "when": "Docs enrichment and per-audience variants.",
  "watch": "Yet another file to keep in sync.",
  "example": "actions: - target: $.info update: {...}",
  "refs": "OpenAPI Overlay Specification, apis.io Overlays",
  "apisio": [
   [
    "Overlays",
    "/overlays/"
   ]
  ]
 },
 {
  "id": "protocol-buffers-idl-contracts",
  "name": "Protocol Buffers / IDL Contracts",
  "category": "Discovery & Contracts",
  "transport": "Both",
  "maturity": "Common",
  "what": "Interface definition languages that generate code for both ends.",
  "when": "gRPC and binary TCP protocols.",
  "watch": "Coordinating schema changes.",
  "example": "message Order { string id = 1; }",
  "refs": "Protobuf, Thrift IDL, Avro, Smithy",
  "apisio": []
 },
 {
  "id": "json-schema",
  "name": "JSON Schema",
  "category": "Discovery & Contracts",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "A vocabulary for validating and describing JSON payloads.",
  "when": "Request/response validation and shared models.",
  "watch": "Dialect differences across tools.",
  "example": "\"$schema\": \"https://json-schema.org/draft/2020-12/schema\"",
  "refs": "JSON Schema 2020-12",
  "apisio": []
 },
 {
  "id": "schema-registry",
  "name": "Schema Registry",
  "category": "Discovery & Contracts",
  "transport": "TCP",
  "maturity": "Common",
  "what": "A central store of versioned message schemas with compatibility checks.",
  "when": "Kafka and other streaming platforms.",
  "watch": "An operational dependency.",
  "example": "Confluent Schema Registry, BACKWARD compatibility",
  "refs": "Confluent, Apicurio",
  "apisio": []
 },
 {
  "id": "apis-json",
  "name": "APIs.json",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A machine-readable index of a provider's APIs and their supporting resources.",
  "when": "Making an API portfolio discoverable.",
  "watch": "Needs to be kept current.",
  "example": "/apis.json",
  "refs": "APIs.json specification",
  "apisio": []
 },
 {
  "id": "well-known-uris",
  "name": "Well-Known URIs",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Predictable /.well-known/ paths for metadata.",
  "when": "OAuth metadata, API catalogs and agent cards.",
  "watch": "Registered names only.",
  "example": "/.well-known/api-catalog",
  "refs": "RFC 8615, RFC 9727",
  "apisio": []
 },
 {
  "id": "oauth-server-metadata",
  "name": "OAuth Server Metadata",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Publish authorization server endpoints and capabilities.",
  "when": "Any OAuth deployment.",
  "watch": "Forgetting protected-resource metadata.",
  "example": "/.well-known/oauth-authorization-server",
  "refs": "RFC 8414, RFC 9728",
  "apisio": []
 },
 {
  "id": "llms-txt",
  "name": "llms.txt",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "A Markdown index of docs written for LLMs.",
  "when": "Helping AI assistants find your docs.",
  "watch": "Not a contract; it is guidance only.",
  "example": "/llms.txt",
  "refs": "llmstxt.org",
  "apisio": []
 },
 {
  "id": "mcp-server",
  "name": "MCP Server",
  "category": "Discovery & Contracts",
  "transport": "Both",
  "maturity": "Emerging",
  "what": "Expose API capabilities as tools, resources and prompts that AI agents can call.",
  "when": "Making an API usable by agents.",
  "watch": "Auth, tool sprawl and per-tenant discovery.",
  "example": "tools/list -> [{\"name\":\"create_order\",...}]",
  "refs": "Model Context Protocol",
  "apisio": []
 },
 {
  "id": "agent-cards-a2a",
  "name": "Agent Cards (A2A)",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "A JSON card describing an agent's skills and endpoints for agent-to-agent calls.",
  "when": "Publishing an agent rather than an API.",
  "watch": "Early standard.",
  "example": "/.well-known/agent-card.json",
  "refs": "Agent2Agent Protocol, apis.io Agents",
  "apisio": [
   [
    "Agents",
    "/agents/"
   ]
  ]
 },
 {
  "id": "sdk-generation",
  "name": "SDK Generation",
  "category": "Discovery & Contracts",
  "transport": "Both",
  "maturity": "Common",
  "what": "Generate typed client libraries from the contract.",
  "when": "Lowering the integration cost across languages.",
  "watch": "Generated code quality varies.",
  "example": "openapi-generator, Fern, Stainless, Speakeasy",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "sandbox-test-mode",
  "name": "Sandbox / Test Mode",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A safe environment with test credentials and fake data.",
  "when": "Payments and anything with real-world side effects.",
  "watch": "Sandboxes that drift from production behavior.",
  "example": "sk_test_... keys",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "mock-servers",
  "name": "Mock Servers",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Serve example responses from the contract before the backend exists.",
  "when": "Design-first development.",
  "watch": "Mocks that lie about behavior.",
  "example": "Prism, Microcks",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "interactive-docs-try-it",
  "name": "Interactive Docs / Try It",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Docs that make live calls.",
  "when": "Learning by doing.",
  "watch": "Exposing production keys.",
  "example": "Swagger UI, Scalar, Redoc",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "self-service-onboarding",
  "name": "Self-Service Onboarding",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Sign up, get a key and make a first call with no humans involved.",
  "when": "Growth-led APIs.",
  "watch": "Abuse and fraud.",
  "example": "Time-to-first-call < 5 min",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "changelog-release-notes",
  "name": "Changelog / Release Notes",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "A dated, machine-readable record of API changes.",
  "when": "Every evolving API.",
  "watch": "Changelogs that skip breaking changes.",
  "example": "/changelog.rss",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "request-response-examples",
  "name": "Request/Response Examples",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Concrete examples for every operation in docs and contracts.",
  "when": "Always; they are how most people learn.",
  "watch": "Examples that are invalid against the schema.",
  "example": "OpenAPI examples object",
  "refs": "OpenAPI, apis.io Examples",
  "apisio": [
   [
    "Examples",
    "/examples/"
   ]
  ]
 },
 {
  "id": "request-response-synchronous-rpc",
  "name": "Request / Response (Synchronous RPC)",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "The client sends a message on a connection and blocks for the matching reply.",
  "when": "Simple query and command protocols.",
  "watch": "Head-of-line blocking without pipelining.",
  "example": "Redis GET key -> $5 hello",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "fire-and-forget-one-way",
  "name": "Fire-and-Forget (One-Way)",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Send a message with no reply expected.",
  "when": "Telemetry, logs and metrics.",
  "watch": "Silent loss.",
  "example": "StatsD UDP packet, syslog",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "publish-subscribe",
  "name": "Publish / Subscribe",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Publishers send to topics; brokers fan messages out to subscribers.",
  "when": "Decoupled many-to-many distribution.",
  "watch": "Delivery guarantees vary by broker.",
  "example": "MQTT PUBLISH sensors/temp",
  "refs": "MQTT, AMQP, NATS, Kafka, apis.io Channels",
  "apisio": [
   [
    "Channels",
    "/channels/"
   ]
  ]
 },
 {
  "id": "point-to-point-queue",
  "name": "Point-to-Point Queue",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Each message is consumed by exactly one worker from a queue.",
  "when": "Work distribution.",
  "watch": "Poison messages; use dead-letter queues.",
  "example": "AMQP queue with competing consumers",
  "refs": "AMQP 0-9-1/1.0, JMS",
  "apisio": []
 },
 {
  "id": "competing-consumers",
  "name": "Competing Consumers",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Several workers read from one queue to scale processing.",
  "when": "Horizontally scaling background work.",
  "watch": "Ordering is lost.",
  "example": "N workers on one SQS queue",
  "refs": "Enterprise Integration Patterns",
  "apisio": []
 },
 {
  "id": "request-reply-over-messaging",
  "name": "Request-Reply over Messaging",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Send a request with a reply-to address and a correlation id over a broker.",
  "when": "RPC semantics across async infrastructure.",
  "watch": "Timeout and orphaned-reply handling.",
  "example": "AMQP reply_to + correlation_id",
  "refs": "Enterprise Integration Patterns",
  "apisio": []
 },
 {
  "id": "push-pull-pipeline",
  "name": "Push / Pull Pipeline",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Distribute tasks downstream and collect results upstream.",
  "when": "Parallel processing pipelines.",
  "watch": "No broker-level persistence.",
  "example": "ZeroMQ PUSH/PULL",
  "refs": "ZeroMQ guide",
  "apisio": []
 },
 {
  "id": "dealer-router",
  "name": "Dealer / Router",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Advanced",
  "what": "Asynchronous, addressable request-reply for brokers and load balancers.",
  "when": "Custom high-performance routing.",
  "watch": "Complex to reason about.",
  "example": "ZeroMQ DEALER/ROUTER",
  "refs": "ZeroMQ guide",
  "apisio": []
 },
 {
  "id": "fan-out-fan-in",
  "name": "Fan-Out / Fan-In",
  "category": "Messaging Patterns",
  "transport": "Both",
  "maturity": "Common",
  "what": "Split work across many recipients, then aggregate the results.",
  "when": "Scatter-gather queries.",
  "watch": "Waiting on the slowest participant.",
  "example": "Scatter-gather search across shards",
  "refs": "Enterprise Integration Patterns",
  "apisio": []
 },
 {
  "id": "bidirectional-streaming",
  "name": "Bidirectional Streaming",
  "category": "Messaging Patterns",
  "transport": "Both",
  "maturity": "Common",
  "what": "Both sides send independent message streams over one connection.",
  "when": "Chat, real-time sync and voice.",
  "watch": "Flow control and error handling.",
  "example": "gRPC bidi stream, WebSocket",
  "refs": "gRPC",
  "apisio": []
 },
 {
  "id": "server-push-stream",
  "name": "Server Push Stream",
  "category": "Messaging Patterns",
  "transport": "Both",
  "maturity": "Common",
  "what": "The server pushes updates on an open connection after one subscribe.",
  "when": "Market data and live state.",
  "watch": "Reconnect and resubscribe logic.",
  "example": "Redis SUBSCRIBE, gRPC server streaming",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "event-log-append-only-stream",
  "name": "Event Log / Append-Only Stream",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Consumers read an ordered, replayable log at their own offsets.",
  "when": "Event sourcing, CDC and analytics pipelines.",
  "watch": "Retention and partition design.",
  "example": "Kafka topic partitions",
  "refs": "Apache Kafka protocol",
  "apisio": []
 },
 {
  "id": "dead-letter-queue",
  "name": "Dead Letter Queue",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Route messages that repeatedly fail into a side queue for inspection.",
  "when": "Any queue consumer.",
  "watch": "DLQs nobody watches.",
  "example": "orders.DLQ",
  "refs": "Enterprise Integration Patterns",
  "apisio": []
 },
 {
  "id": "message-ordering-keys",
  "name": "Message Ordering Keys",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Advanced",
  "what": "Guarantee order per key (partition) rather than globally.",
  "when": "Per-entity ordering at scale.",
  "watch": "Hot keys.",
  "example": "Kafka partition key = customer_id",
  "refs": "Kafka",
  "apisio": []
 },
 {
  "id": "exactly-once-effectively-once",
  "name": "Exactly-Once / Effectively-Once",
  "category": "Messaging Patterns",
  "transport": "TCP",
  "maturity": "Advanced",
  "what": "Idempotent producers plus transactional consumption to avoid duplicates.",
  "when": "Financial and stateful stream processing.",
  "watch": "Narrow guarantees and real cost.",
  "example": "Kafka idempotent producer + transactions",
  "refs": "Kafka EOS",
  "apisio": []
 },
 {
  "id": "length-prefixed-framing",
  "name": "Length-Prefixed Framing",
  "category": "Framing & Encoding",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Each message begins with its byte length.",
  "when": "Binary protocols over streams.",
  "watch": "Max-length checks against hostile peers.",
  "example": "[uint32 len][payload]",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "delimiter-based-framing",
  "name": "Delimiter-Based Framing",
  "category": "Framing & Encoding",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Messages end with a delimiter such as CRLF or a newline.",
  "when": "Text protocols that people can debug with telnet.",
  "watch": "Escaping delimiters inside payloads.",
  "example": "SMTP, Redis RESP, NDJSON over TCP",
  "refs": "RFC 5321, RESP",
  "apisio": []
 },
 {
  "id": "fixed-length-records",
  "name": "Fixed-Length Records",
  "category": "Framing & Encoding",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Every message is exactly N bytes.",
  "when": "Legacy, mainframe and hardware protocols.",
  "watch": "Wasted space, rigid evolution.",
  "example": "ISO 8583 fixed fields",
  "refs": "ISO 8583",
  "apisio": []
 },
 {
  "id": "type-length-value-tlv",
  "name": "Type-Length-Value (TLV)",
  "category": "Framing & Encoding",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Fields are encoded as type, length and value, so unknown fields can be skipped.",
  "when": "Extensible binary protocols.",
  "watch": "Parsing overhead.",
  "example": "RADIUS attributes, EMV tags",
  "refs": "RFC 2865, ASN.1 BER",
  "apisio": []
 },
 {
  "id": "protocol-buffers-encoding",
  "name": "Protocol Buffers Encoding",
  "category": "Framing & Encoding",
  "transport": "Both",
  "maturity": "Common",
  "what": "Compact, tagged binary encoding with forward and backward compatibility.",
  "when": "Typed, efficient RPC and messaging.",
  "watch": "Not self-describing without the schema.",
  "example": "varint field tags",
  "refs": "Protocol Buffers",
  "apisio": []
 },
 {
  "id": "avro-thrift-cap-n-proto",
  "name": "Avro / Thrift / Cap'n Proto",
  "category": "Framing & Encoding",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Alternative schema-based binary encodings with different evolution and zero-copy tradeoffs.",
  "when": "Streaming (Avro), RPC (Thrift), zero-copy (Cap'n Proto).",
  "watch": "Ecosystem lock-in.",
  "example": "Avro with a schema registry",
  "refs": "Apache Avro, Apache Thrift, Cap'n Proto",
  "apisio": []
 },
 {
  "id": "messagepack-cbor",
  "name": "MessagePack / CBOR",
  "category": "Framing & Encoding",
  "transport": "Both",
  "maturity": "Common",
  "what": "Schemaless binary JSON-like encodings.",
  "when": "You want JSON semantics with smaller, faster payloads.",
  "watch": "Harder to inspect than JSON.",
  "example": "CBOR in COSE/WebAuthn",
  "refs": "RFC 8949, MessagePack spec",
  "apisio": []
 },
 {
  "id": "multiplexed-streams-over-one-connection",
  "name": "Multiplexed Streams over One Connection",
  "category": "Framing & Encoding",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Frames carry stream ids so many logical conversations share one socket.",
  "when": "Reducing connection overhead.",
  "watch": "One slow stream can starve others without flow control.",
  "example": "HTTP/2 stream id, yamux, SSH channels",
  "refs": "RFC 9113, yamux",
  "apisio": []
 },
 {
  "id": "pipelining",
  "name": "Pipelining",
  "category": "Framing & Encoding",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Send several requests without waiting for replies, which come back in order.",
  "when": "Cutting round trips on high-latency links.",
  "watch": "Head-of-line blocking.",
  "example": "Redis pipeline of 100 SETs",
  "refs": "RESP, HTTP/1.1 pipelining",
  "apisio": []
 },
 {
  "id": "correlation-ids-for-out-of-order-replies",
  "name": "Correlation IDs for Out-of-Order Replies",
  "category": "Framing & Encoding",
  "transport": "Both",
  "maturity": "Common",
  "what": "Tag each request so responses can arrive in any order.",
  "when": "Async multiplexed RPC.",
  "watch": "Unbounded tables of outstanding requests.",
  "example": "JSON-RPC id, Kafka correlation_id",
  "refs": "JSON-RPC, Kafka protocol",
  "apisio": []
 },
 {
  "id": "handshake-capability-negotiation",
  "name": "Handshake / Capability Negotiation",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Peers exchange versions and features before real traffic.",
  "when": "Evolving protocols with mixed client versions.",
  "watch": "Downgrade attacks.",
  "example": "TLS ClientHello, MCP initialize, AMQP Connection.Start",
  "refs": "RFC 8446, MCP",
  "apisio": []
 },
 {
  "id": "persistent-connections-keep-alive",
  "name": "Persistent Connections / Keep-Alive",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Reuse one connection for many requests.",
  "when": "Avoiding handshake cost.",
  "watch": "Idle connections killed by NATs and load balancers.",
  "example": "Connection: keep-alive",
  "refs": "RFC 9112",
  "apisio": []
 },
 {
  "id": "connection-pooling",
  "name": "Connection Pooling",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Clients keep a pool of warm connections.",
  "when": "High-throughput clients of databases and services.",
  "watch": "Pool exhaustion and stale connections.",
  "example": "HikariCP, pgbouncer",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "heartbeats-ping-pong",
  "name": "Heartbeats / Ping-Pong",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Periodic frames prove the peer is alive and keep NAT mappings open.",
  "when": "Long-lived connections.",
  "watch": "Choosing intervals and timeouts.",
  "example": "WebSocket ping, MQTT PINGREQ, AMQP heartbeat",
  "refs": "RFC 6455, MQTT",
  "apisio": []
 },
 {
  "id": "reconnect-with-backoff",
  "name": "Reconnect with Backoff",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Clients reconnect automatically after drops with increasing delays.",
  "when": "Every long-lived client.",
  "watch": "Thundering herds after an outage; add jitter.",
  "example": "1s, 2s, 4s... + jitter",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "session-resumption",
  "name": "Session Resumption",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Resume a session's state or position after reconnecting.",
  "when": "Mobile clients and flaky networks.",
  "watch": "Server-side session storage.",
  "example": "MQTT clean_session=false, TLS session tickets, SSE Last-Event-ID",
  "refs": "MQTT, RFC 8446",
  "apisio": []
 },
 {
  "id": "graceful-shutdown-draining",
  "name": "Graceful Shutdown / Draining",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Common",
  "what": "Tell peers to stop opening new streams and finish in-flight work.",
  "when": "Deploys and scaling events.",
  "watch": "Clients that ignore the signal.",
  "example": "HTTP/2 GOAWAY",
  "refs": "RFC 9113",
  "apisio": []
 },
 {
  "id": "stateful-session-vs-stateless",
  "name": "Stateful Session vs Stateless",
  "category": "Connection Management",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "Decide whether a connection carries context (auth, transactions) or each message stands alone.",
  "when": "Choosing protocol architecture.",
  "watch": "Stateful sessions complicate load balancing and failover.",
  "example": "Postgres session vs HTTP request",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "sasl-authentication-exchange",
  "name": "SASL Authentication Exchange",
  "category": "Connection Management",
  "transport": "TCP",
  "maturity": "Common",
  "what": "A pluggable challenge-response auth step at connection time.",
  "when": "Messaging, mail and database protocols.",
  "watch": "Mechanism negotiation complexity.",
  "example": "AUTH SCRAM-SHA-256",
  "refs": "RFC 4422",
  "apisio": []
 },
 {
  "id": "tls-mtls-on-raw-sockets",
  "name": "TLS / mTLS on Raw Sockets",
  "category": "Connection Management",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Encrypt and authenticate TCP streams.",
  "when": "Every protocol on an untrusted network.",
  "watch": "Certificate rotation.",
  "example": "STARTTLS, TLS-wrapped port",
  "refs": "RFC 8446",
  "apisio": []
 },
 {
  "id": "backpressure",
  "name": "Backpressure",
  "category": "Flow Control & Reliability",
  "transport": "Both",
  "maturity": "Common",
  "what": "Slow receivers signal senders to slow down instead of buffering unbounded data.",
  "when": "Streams where the producer can outpace the consumer.",
  "watch": "Ignoring it leads to memory blow-ups.",
  "example": "Reactive Streams request(n)",
  "refs": "Reactive Streams",
  "apisio": []
 },
 {
  "id": "credit-based-flow-control-windowing",
  "name": "Credit-Based Flow Control / Windowing",
  "category": "Flow Control & Reliability",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Receivers grant credits or windows for how much may be sent.",
  "when": "Multiplexed and high-throughput protocols.",
  "watch": "Window tuning.",
  "example": "HTTP/2 WINDOW_UPDATE, AMQP 1.0 link credit",
  "refs": "RFC 9113, AMQP 1.0",
  "apisio": []
 },
 {
  "id": "acknowledgements-ack-nack",
  "name": "Acknowledgements (Ack / Nack)",
  "category": "Flow Control & Reliability",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Consumers confirm processing so brokers can redeliver failed messages.",
  "when": "Reliable message processing.",
  "watch": "Acking before processing loses messages.",
  "example": "basic.ack / basic.nack",
  "refs": "AMQP 0-9-1",
  "apisio": []
 },
 {
  "id": "delivery-guarantees-qos-levels",
  "name": "Delivery Guarantees (QoS Levels)",
  "category": "Flow Control & Reliability",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Choose at-most-once, at-least-once or exactly-once per message.",
  "when": "Balancing reliability against cost.",
  "watch": "Higher guarantees cost latency.",
  "example": "MQTT QoS 0/1/2",
  "refs": "MQTT",
  "apisio": []
 },
 {
  "id": "sequence-numbers-and-replay",
  "name": "Sequence Numbers and Replay",
  "category": "Flow Control & Reliability",
  "transport": "Both",
  "maturity": "Common",
  "what": "Number messages so gaps and duplicates can be detected and replayed.",
  "when": "Market data feeds and sync protocols.",
  "watch": "Retention windows.",
  "example": "FIX MsgSeqNum + ResendRequest",
  "refs": "FIX protocol",
  "apisio": []
 },
 {
  "id": "batching-and-nagle-tuning",
  "name": "Batching and Nagle Tuning",
  "category": "Flow Control & Reliability",
  "transport": "TCP",
  "maturity": "Advanced",
  "what": "Group small writes for throughput, or disable Nagle for latency.",
  "when": "Latency- vs throughput-sensitive sockets.",
  "watch": "Delayed ACK interaction.",
  "example": "TCP_NODELAY",
  "refs": "RFC 896",
  "apisio": []
 },
 {
  "id": "snapshot-incremental-updates",
  "name": "Snapshot + Incremental Updates",
  "category": "Flow Control & Reliability",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Send the full state first, then deltas, resyncing on gaps.",
  "when": "Order books, collaborative docs and caches.",
  "watch": "Snapshot cost.",
  "example": "Exchange L2 book snapshot then diffs",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "request-queueing-admission-control",
  "name": "Request Queueing / Admission Control",
  "category": "Flow Control & Reliability",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Bound the number of in-flight requests and queue or reject the excess.",
  "when": "Protecting servers from overload.",
  "watch": "Queue-induced latency.",
  "example": "max_concurrent_streams",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "l4-vs-l7-load-balancing",
  "name": "L4 vs L7 Load Balancing",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Common",
  "what": "Balance by connection (TCP) or by request (HTTP).",
  "when": "Long-lived connections need L7 or client-side balancing.",
  "watch": "L4 balancing pins gRPC streams to a single backend.",
  "example": "NLB vs ALB, Envoy",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "client-side-load-balancing",
  "name": "Client-Side Load Balancing",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Clients discover endpoints and balance across them directly.",
  "when": "gRPC and internal meshes.",
  "watch": "Clients need service discovery.",
  "example": "gRPC xDS load balancing",
  "refs": "xDS API",
  "apisio": []
 },
 {
  "id": "service-discovery",
  "name": "Service Discovery",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Common",
  "what": "Look up service endpoints dynamically.",
  "when": "Elastic microservice environments.",
  "watch": "Stale registrations.",
  "example": "DNS SRV, Consul, Kubernetes Services",
  "refs": "RFC 2782",
  "apisio": []
 },
 {
  "id": "sidecar-service-mesh",
  "name": "Sidecar / Service Mesh",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Common",
  "what": "A proxy beside each service handles mTLS, retries and telemetry.",
  "when": "Uniform cross-cutting policy across many services.",
  "watch": "Operational weight.",
  "example": "Istio, Linkerd, Envoy",
  "refs": "xDS, SPIFFE",
  "apisio": []
 },
 {
  "id": "sticky-sessions",
  "name": "Sticky Sessions",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Common",
  "what": "Route a client consistently to the same backend.",
  "when": "Stateful connections and in-memory sessions.",
  "watch": "Uneven load and painful failover.",
  "example": "Cookie- or IP-hash affinity",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "reverse-proxy",
  "name": "Reverse Proxy",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Foundational",
  "what": "An intermediary terminates client connections and forwards them to backends.",
  "when": "TLS termination, routing and caching.",
  "watch": "Header and timeout mismatches.",
  "example": "Nginx, HAProxy",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "reactor-event-loop-server",
  "name": "Reactor / Event Loop Server",
  "category": "Topology & Infrastructure",
  "transport": "TCP",
  "maturity": "Common",
  "what": "One thread multiplexes many non-blocking sockets.",
  "when": "High-concurrency, IO-bound servers.",
  "watch": "Blocking calls freeze everything.",
  "example": "Node.js, Netty, epoll",
  "refs": "Reactor pattern (Schmidt)",
  "apisio": []
 },
 {
  "id": "thread-per-connection",
  "name": "Thread-per-Connection",
  "category": "Topology & Infrastructure",
  "transport": "TCP",
  "maturity": "Foundational",
  "what": "Each connection gets a dedicated thread.",
  "when": "Simple servers with modest concurrency.",
  "watch": "Memory and context-switch cost at scale.",
  "example": "Classic Apache prefork",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "broker-vs-brokerless",
  "name": "Broker vs Brokerless",
  "category": "Topology & Infrastructure",
  "transport": "TCP",
  "maturity": "Common",
  "what": "Route messages through a central broker, or peer-to-peer.",
  "when": "Trading operational simplicity against latency.",
  "watch": "A broker is a dependency; brokerless pushes complexity into clients.",
  "example": "RabbitMQ vs ZeroMQ",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "tunneling-over-http",
  "name": "Tunneling over HTTP",
  "category": "Topology & Infrastructure",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Carry TCP or UDP traffic through HTTP CONNECT or MASQUE.",
  "when": "Traversing restrictive networks.",
  "watch": "Visibility and security review.",
  "example": "CONNECT host:443, CONNECT-UDP",
  "refs": "RFC 9110 CONNECT, RFC 9298",
  "apisio": []
 },
 {
  "id": "agent-tool-calling",
  "name": "Agent Tool Calling",
  "category": "AI & Agent Patterns",
  "transport": "Both",
  "maturity": "Emerging",
  "what": "Describe operations so LLMs can choose and invoke them with structured arguments.",
  "when": "Exposing APIs to AI agents.",
  "watch": "Vague descriptions mean the wrong tool gets picked.",
  "example": "Function/tool schemas derived from OpenAPI",
  "refs": "MCP, OpenAPI",
  "apisio": []
 },
 {
  "id": "natural-language-operation-descriptions",
  "name": "Natural-Language Operation Descriptions",
  "category": "AI & Agent Patterns",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Write operation summaries and descriptions for machine reasoning, not just humans.",
  "when": "Agents and search will consume your contract.",
  "watch": "Marketing-speak descriptions.",
  "example": "summary: \"Refund a captured charge, fully or partially\"",
  "refs": "OpenAPI",
  "apisio": []
 },
 {
  "id": "agent-readable-errors",
  "name": "Agent-Readable Errors",
  "category": "AI & Agent Patterns",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Errors explain what to change and point to the fix, so agents can self-correct.",
  "when": "Autonomous clients.",
  "watch": "Leaking internals.",
  "example": "{\"detail\":\"amount must be <= 5000; split into two calls\"}",
  "refs": "RFC 9457",
  "apisio": []
 },
 {
  "id": "human-in-the-loop-confirmation",
  "name": "Human-in-the-Loop Confirmation",
  "category": "AI & Agent Patterns",
  "transport": "Both",
  "maturity": "Emerging",
  "what": "Destructive or costly operations require explicit confirmation or elicitation.",
  "when": "Agents acting on users' behalf.",
  "watch": "Prompt fatigue.",
  "example": "MCP elicitation, two-step confirm tokens",
  "refs": "MCP",
  "apisio": []
 },
 {
  "id": "scoped-agent-credentials",
  "name": "Scoped Agent Credentials",
  "category": "AI & Agent Patterns",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Short-lived, narrowly scoped, auditable tokens issued to agents.",
  "when": "Letting agents act without full user power.",
  "watch": "Delegation chains are hard to audit.",
  "example": "Token exchange with an actor claim",
  "refs": "RFC 8693, RFC 9396",
  "apisio": []
 },
 {
  "id": "agent-to-agent-messaging",
  "name": "Agent-to-Agent Messaging",
  "category": "AI & Agent Patterns",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Agents discover and delegate tasks to each other through published cards and task APIs.",
  "when": "Multi-agent systems across organizations.",
  "watch": "Trust and identity are unresolved.",
  "example": "A2A tasks/send",
  "refs": "Agent2Agent Protocol",
  "apisio": []
 },
 {
  "id": "free-tier",
  "name": "Free Tier",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "A no-cost plan with limited volume or features, so developers can build before they buy.",
  "when": "Developer-led adoption, where the first call should never need a credit card.",
  "watch": "A free tier that is too small to prove value, or so generous nobody upgrades.",
  "example": "1,000 calls/month free",
  "refs": "apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "freemium-to-paid-tiers",
  "name": "Freemium to Paid Tiers",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Good/better/best plans that bundle quotas, features and support levels.",
  "when": "Serving hobbyists through to enterprises with one product.",
  "watch": "Too many tiers; feature gating that blocks evaluation.",
  "example": "Free, Pro $49, Business $499, Enterprise",
  "refs": "apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "pay-as-you-go-metered",
  "name": "Pay-As-You-Go / Metered",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Charge per call, per unit (message, minute, GB, token) with no commitment.",
  "when": "Usage varies widely and customers want to start small.",
  "watch": "Bill shock; publish calculators and alerts.",
  "example": "$0.0079 per SMS segment",
  "refs": "apis.io Plans, apis.io FinOps",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ],
   [
    "FinOps",
    "/finops/"
   ]
  ]
 },
 {
  "id": "tiered-volume-pricing",
  "name": "Tiered / Volume Pricing",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The unit price drops as volume crosses thresholds.",
  "when": "Rewarding growth and large customers.",
  "watch": "Graduated vs volume tiers confuse buyers, so state which one you use.",
  "example": "First 1M calls $2/1K, next 9M $1.50/1K",
  "refs": "apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "committed-use-prepaid-credits",
  "name": "Committed Use / Prepaid Credits",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Customers prepay or commit to spend in exchange for discounts.",
  "when": "Predictable revenue and enterprise budgets.",
  "watch": "Expiring credits feel punitive.",
  "example": "$10K annual commit, 20% off list",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "seat-or-subscription-pricing-with-api-access",
  "name": "Seat or Subscription Pricing with API Access",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "The API comes bundled with a SaaS subscription, priced per seat or account.",
  "when": "The API extends a product people already pay for.",
  "watch": "API access gated to top tiers frustrates integrators.",
  "example": "API available on Business plan and above",
  "refs": "apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "outcome-value-based-pricing",
  "name": "Outcome / Value-Based Pricing",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Charge on the business result, such as a percentage of a payment or a successful verification.",
  "when": "The API's value tracks a measurable outcome.",
  "watch": "Disputes over what counted as a success.",
  "example": "2.9% + 30¢ per successful charge",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "token-compute-based-pricing",
  "name": "Token / Compute-Based Pricing",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Price on model tokens, compute seconds or credits consumed.",
  "when": "AI and compute-heavy APIs.",
  "watch": "Hard for buyers to forecast.",
  "example": "$3 per million input tokens",
  "refs": "apis.io FinOps",
  "apisio": [
   [
    "FinOps",
    "/finops/"
   ]
  ]
 },
 {
  "id": "revenue-share-marketplace",
  "name": "Revenue Share / Marketplace",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Partners build on the API and split revenue through a marketplace or app store.",
  "when": "Platform ecosystems.",
  "watch": "Partner conflict and the platform competing with its own partners.",
  "example": "App marketplace with a 20% platform fee",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "partner-indirect-distribution",
  "name": "Partner / Indirect Distribution",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Sell API access through cloud marketplaces, resellers or aggregators.",
  "when": "Reaching enterprise procurement channels.",
  "watch": "Margin and support handoffs.",
  "example": "AWS Marketplace, RapidAPI listing",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "enterprise-contact-sales",
  "name": "Enterprise / Contact Sales",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Custom contracts, volumes, SLAs and terms negotiated with sales.",
  "when": "Large, regulated or high-volume customers.",
  "watch": "\"Contact us\" pricing hides cost from evaluators.",
  "example": "Enterprise: custom pricing",
  "refs": "apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "published-pricing-page",
  "name": "Published Pricing Page",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "Public, specific, machine-readable prices and limits per plan.",
  "when": "Always; buyers and agents both compare on it.",
  "watch": "Prices that drift from what billing charges.",
  "example": "/pricing with per-unit rates",
  "refs": "apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "machine-readable-plans",
  "name": "Machine-Readable Plans",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Plans, prices, limits and entitlements published as structured data an agent can read.",
  "when": "Agents and procurement tools need to compare APIs.",
  "watch": "Keeping it in sync with the pricing page.",
  "example": "plans.yml referenced from apis.json",
  "refs": "API Commons plans, apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ]
  ]
 },
 {
  "id": "agent-payments-pay-per-call",
  "name": "Agent Payments / Pay-per-Call",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Agents pay per request in-band, without a pre-existing account.",
  "when": "Long-tail, anonymous or agent-driven consumption.",
  "watch": "Immature standards and fraud.",
  "example": "402 Payment Required with a payment challenge",
  "refs": "x402, HTTP 402",
  "apisio": []
 },
 {
  "id": "billing-and-invoicing-apis",
  "name": "Billing and Invoicing APIs",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Expose usage, invoices and spend to customers programmatically.",
  "when": "FinOps teams reconcile API spend.",
  "watch": "Usage data that lags billing.",
  "example": "GET /billing/usage, GET /invoices",
  "refs": "apis.io FinOps",
  "apisio": [
   [
    "FinOps",
    "/finops/"
   ]
  ]
 },
 {
  "id": "spend-alerts-and-caps",
  "name": "Spend Alerts and Caps",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Customer-set budgets that notify or hard-stop at thresholds.",
  "when": "Pay-as-you-go APIs.",
  "watch": "Hard caps that break production unexpectedly.",
  "example": "Alert at $500, cap at $1,000",
  "refs": "apis.io FinOps",
  "apisio": [
   [
    "FinOps",
    "/finops/"
   ]
  ]
 },
 {
  "id": "overage-policy",
  "name": "Overage Policy",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A defined behavior when quota is exceeded: block, throttle, or bill extra.",
  "when": "Any quota-based plan.",
  "watch": "Undocumented overage charges.",
  "example": "$0.002 per call over plan",
  "refs": "apis.io Rate Limits, apis.io Plans",
  "apisio": [
   [
    "Plans",
    "/plans/"
   ],
   [
    "Rate Limits",
    "/rate-limits/"
   ]
  ]
 },
 {
  "id": "eligibility-and-access-requirements",
  "name": "Eligibility and Access Requirements",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Who may use the API: approval, KYC, region, partner status or business type.",
  "when": "Regulated, partner or restricted APIs.",
  "watch": "Opaque approval processes stall developers.",
  "example": "Production access after KYB review",
  "refs": "apis.io Eligibility",
  "apisio": [
   [
    "Eligibility",
    "/eligibility/"
   ]
  ]
 },
 {
  "id": "service-level-agreement-sla",
  "name": "Service Level Agreement (SLA)",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Contractual uptime, latency and support commitments with credits.",
  "when": "Enterprise and paid tiers.",
  "watch": "SLAs without measurement or published status.",
  "example": "99.95% monthly uptime, 10% credit below",
  "refs": "apis.io SLA",
  "apisio": [
   [
    "SLA",
    "/sla/"
   ]
  ]
 },
 {
  "id": "support-tiers",
  "name": "Support Tiers",
  "category": "Business & Pricing",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Response-time commitments by plan (community, email, dedicated).",
  "when": "Paid plans differentiated by support.",
  "watch": "Promising response times you cannot staff.",
  "example": "Business: 4h response, 24x7",
  "refs": "Common practice",
  "apisio": []
 },
 {
  "id": "terms-of-service",
  "name": "Terms of Service",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "The legal terms for using the API: acceptable use, liability, termination.",
  "when": "Every public API.",
  "watch": "Terms that forbid the use cases you market.",
  "example": "/legal/api-terms",
  "refs": "apis.io Terms",
  "apisio": [
   [
    "Terms",
    "/terms/"
   ]
  ]
 },
 {
  "id": "privacy-policy-and-data-processing",
  "name": "Privacy Policy and Data Processing",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Foundational",
  "what": "How personal data passing through the API is collected, processed and retained, plus DPAs.",
  "when": "Any API touching personal data.",
  "watch": "Policies that ignore API data flows.",
  "example": "/privacy, DPA available on request",
  "refs": "apis.io Privacy, GDPR",
  "apisio": [
   [
    "Privacy",
    "/privacy/"
   ]
  ]
 },
 {
  "id": "data-licensing",
  "name": "Data Licensing",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Explicit license on the data the API returns: open, attribution, commercial, or restricted.",
  "when": "Data APIs, open data and content APIs.",
  "watch": "Silence, which leaves reuse legally unclear.",
  "example": "CC BY 4.0, ODbL, proprietary",
  "refs": "apis.io Data Licenses",
  "apisio": [
   [
    "Data Licenses",
    "/data-licenses/"
   ]
  ]
 },
 {
  "id": "api-definition-licensing",
  "name": "API Definition Licensing",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "License the contract (OpenAPI, SDKs) separately from the service so others can reuse it.",
  "when": "Encouraging ecosystem tooling and interoperability.",
  "watch": "Unlicensed specs block forks and mirrors.",
  "example": "OpenAPI under Apache 2.0",
  "refs": "Oracle v. Google context, API Commons",
  "apisio": []
 },
 {
  "id": "ai-usage-preferences",
  "name": "AI Usage Preferences",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "State whether content and data may be used to train or ground AI, in machine-readable form.",
  "when": "Content and data providers deciding on AI terms.",
  "watch": "Signals that are not enforced.",
  "example": "ai.txt, robots.txt AI agents, Content-Usage header",
  "refs": "IETF AI Preferences WG, apis.io AI Preferences",
  "apisio": [
   [
    "AI Preferences",
    "/ai-preferences/"
   ]
  ]
 },
 {
  "id": "compliance-attestations",
  "name": "Compliance Attestations",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Publish the certifications and frameworks the API meets.",
  "when": "Enterprise and regulated buyers.",
  "watch": "Badges without current reports.",
  "example": "SOC 2 Type II, ISO 27001, PCI DSS, HIPAA",
  "refs": "apis.io Compliance",
  "apisio": [
   [
    "Compliance",
    "/compliance/"
   ]
  ]
 },
 {
  "id": "regulatory-alignment",
  "name": "Regulatory Alignment",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Design to a sector's mandated API rules: open banking, healthcare interoperability, payments.",
  "when": "APIs in regulated industries.",
  "watch": "Treating compliance as documentation instead of design.",
  "example": "FAPI, FHIR, PSD2, CFPB 1033",
  "refs": "apis.io Regulations",
  "apisio": [
   [
    "Regulations",
    "/regulations/"
   ]
  ]
 },
 {
  "id": "data-residency",
  "name": "Data Residency",
  "category": "Policy & Legal",
  "transport": "Both",
  "maturity": "Advanced",
  "what": "Let customers pin data and processing to regions.",
  "when": "Sovereignty and regulatory requirements.",
  "watch": "Regional endpoints fragment discovery.",
  "example": "https://eu.api.example.com",
  "refs": "apis.io Compliance",
  "apisio": [
   [
    "Compliance",
    "/compliance/"
   ]
  ]
 },
 {
  "id": "deprecation-policy",
  "name": "Deprecation Policy",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "A published commitment on notice periods and the support lifetime of versions.",
  "when": "Any API with paying or production consumers.",
  "watch": "Policies nobody follows.",
  "example": "12 months notice for breaking changes",
  "refs": "apis.io Deprecation, RFC 9745",
  "apisio": [
   [
    "Deprecation",
    "/deprecation/"
   ]
  ]
 },
 {
  "id": "security-disclosure-security-txt",
  "name": "Security Disclosure (security.txt)",
  "category": "Policy & Legal",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Tell researchers how to report vulnerabilities.",
  "when": "Every public API.",
  "watch": "An unmonitored inbox.",
  "example": "/.well-known/security.txt",
  "refs": "RFC 9116, apis.io Security",
  "apisio": [
   [
    "Security",
    "/security/"
   ]
  ]
 },
 {
  "id": "postman-collections",
  "name": "Postman Collections",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Runnable request collections that let developers try an API immediately.",
  "when": "Onboarding and testing.",
  "watch": "Collections that drift from the contract.",
  "example": "Run in Postman button",
  "refs": "Postman Collection format, apis.io Collections",
  "apisio": [
   [
    "Collections",
    "/collections/"
   ]
  ]
 },
 {
  "id": "json-ld-linked-data",
  "name": "JSON-LD / Linked Data",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Annotate payloads and pages with linked-data context so machines understand meaning.",
  "when": "Search engines, knowledge graphs and agents.",
  "watch": "Vocabulary choice and upkeep.",
  "example": "\"@context\": \"https://schema.org\"",
  "refs": "W3C JSON-LD, apis.io JSON-LD",
  "apisio": [
   [
    "JSON-LD",
    "/jsonld/"
   ]
  ]
 },
 {
  "id": "spectral-governance-rules",
  "name": "Spectral / Governance Rules",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Codify the API style guide as lintable rules run in CI.",
  "when": "More than one team designs APIs.",
  "watch": "Rules nobody can explain get waived.",
  "example": "operation-operationId: error",
  "refs": "Spectral, apis.io Rules",
  "apisio": [
   [
    "Rules",
    "/rules/"
   ]
  ]
 },
 {
  "id": "vendor-extensions",
  "name": "Vendor Extensions",
  "category": "Discovery & Contracts",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "x- properties that carry metadata the specification does not.",
  "when": "Gateways, codegen and docs need extra hints.",
  "watch": "Proprietary lock-in.",
  "example": "x-ratelimit-limit, x-codeSamples",
  "refs": "OpenAPI extensions, apis.io Extensions",
  "apisio": [
   [
    "Extensions",
    "/extensions/"
   ]
  ]
 },
 {
  "id": "public-source-repository",
  "name": "Public Source Repository",
  "category": "Developer Experience",
  "transport": "HTTP",
  "maturity": "Common",
  "what": "Contracts, SDKs and examples live in public version control with issues open.",
  "when": "Building trust and accepting fixes from consumers.",
  "watch": "Stale repos signal an abandoned API.",
  "example": "github.com/acme/openapi",
  "refs": "apis.io VCS",
  "apisio": [
   [
    "VCS",
    "/vcs/"
   ]
  ]
 },
 {
  "id": "agent-skills",
  "name": "Agent Skills",
  "category": "AI & Agent Patterns",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Packaged instructions and scripts that teach an agent to use your API well.",
  "when": "Agents misuse an API without guidance.",
  "watch": "Skills that drift from the API.",
  "example": "SKILL.md bundle",
  "refs": "Agent Skills, apis.io Skills",
  "apisio": [
   [
    "Skills",
    "/skills/"
   ]
  ]
 },
 {
  "id": "business-capabilities-map",
  "name": "Business Capabilities Map",
  "category": "AI & Agent Patterns",
  "transport": "HTTP",
  "maturity": "Emerging",
  "what": "Describe what the API lets a business accomplish, mapped to the operations behind it.",
  "when": "Buyers and agents search by outcome, not endpoint.",
  "watch": "Capability lists that do not tie to real operations.",
  "example": "\"Collect a payment\" -> POST /charges",
  "refs": "apis.io Capabilities",
  "apisio": [
   [
    "Capabilities",
    "/capabilities/"
   ]
  ]
 },
 {
  "id": "api-estate-portfolio",
  "name": "API Estate / Portfolio",
  "category": "Topology & Infrastructure",
  "transport": "HTTP",
  "maturity": "Advanced",
  "what": "Manage many APIs across brands, acquisitions and teams as one governed estate.",
  "when": "Large companies with dozens of API products.",
  "watch": "Duplicate, inconsistent APIs across business units.",
  "example": "One owner, 37 provider listings",
  "refs": "apis.io Estates",
  "apisio": [
   [
    "Estates",
    "/estates/"
   ]
  ]
 }
]