# Vendor facets — Amazon API Gateway. A managed gateway with usage plans, API keys and throttling, an
# OpenAPI 3.0 / Swagger 2.0 export of any deployed stage, API Gateway Portals (Nov 2025) with generated
# docs and Try It, and REST stages as MCP targets of Bedrock AgentCore Gateway. What it cannot reach:
# any rate-limit header (throttling returns a bare 429), self-service key sign-up on the portal (Cognito
# access control only), pricing, OAuth discovery, and an MCP server on the provider's own domain.
vendor: aws-api-gateway
name: Amazon API Gateway
website: https://aws.amazon.com/api-gateway/
areas:
- api-gateway
registry_keys:
- aws-api-gateway
rubric_schema_version: 0.22.0
generated: '2026-09-25'
features_refreshed: '2026-09-25'
basis: capability
summary: >-
  API Gateway's most distinctive lift is the contract: any deployed REST stage exports as OpenAPI 3.0,
  so a provider that built its API in the console can publish a machine-readable contract it never wrote
  — thin on descriptions and examples unless the provider documents methods and models first. Portals
  add a generated reference and Try It once declared. Throttling emits no rate-limit headers, the portal
  gates on Cognito rather than self-service keys, and the MCP route runs through AgentCore Gateway on
  an AWS host, graded `platform` (0.25).
features:
- id: openapi-export
  name: Export a REST API stage as OpenAPI 3.0 or Swagger 2.0
  description: >-
    GET /restapis/{id}/stages/{stage}/exports/oas30 (or swagger) in JSON or YAML, optionally with API
    Gateway integration or Postman extensions; only application/json models export.
  source: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html
  tier: all
- id: portals
  name: API Gateway portals
  description: >-
    Managed portals of portal products (groups of REST APIs) with generated per-endpoint docs, custom
    product pages, custom domain or AWS default domain, and cross-account sharing; access controlled only
    through Cognito user pools.
  source: https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-portals.html
  tier: all
- id: portal-try-it
  name: Portal Try It
  description: Consumers enter parameters and headers and see live responses from the portal, with built-in
    limits.
  source: >-
    https://aws.amazon.com/blogs/compute/improve-api-discoverability-with-the-new-amazon-api-gateway-portal/
  tier: all
- id: throttling-usage-plans
  name: Throttling, usage plans and API keys
  description: >-
    Token-bucket throttling at account, stage, method and per-client (API key in a usage plan) levels,
    returning 429 Too Many Requests; quotas per usage plan.
  source: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
  tier: all
- id: agentcore-mcp-target
  name: REST API stage as an AgentCore Gateway MCP target
  description: >-
    A deployed public REST stage becomes MCP tools (one per method, named by operationName) behind a Bedrock
    AgentCore Gateway MCP URL; outbound auth by API key, IAM role or none.
  source: https://docs.aws.amazon.com/apigateway/latest/developerguide/mcp-server.html
  tier: paid
maps:
- feature: openapi-export
  check: contract_present
  layer: composite
  creates_artifact: true
  note: >-
    For a provider that built its API in the console and has no contract, the stage export creates the
    OpenAPI artifact class. The contract describes what is configured — paths, methods, JSON models —
    so the quality checks downstream depend on how much the provider documented.
  provider_must: Export the stage and publish the document on its own domain or repo, declared in apis.yml.
  catalog_pass_rate: 0.31
  facet: contract_quality
  points: 20
  baseline_pass_rate: 0.949
  saturated: true
  saturated_note: >-
    95% of providers with a contract, docs and a reference already earn this; the vendor cannot move it
    for most of its buyers.
- feature: openapi-export
  check: openapi_3_0
  layer: composite
  provider_must: Export with /exports/oas30 (not swagger) and publish that document.
  catalog_pass_rate: 0.459
  facet: contract_quality
  points: 3
  baseline_pass_rate: 0.506
- feature: openapi-export
  check: servers_defined
  layer: composite
  conditional: true
  condition: >-
    Only if the published export carries the provider's custom domain rather than the execute-api.amazonaws.com
    invoke URL — the check needs real servers and servers_resolvable wants a host the provider controls.
  catalog_pass_rate: 0.782
  facet: contract_quality
  points: 3
  baseline_pass_rate: 0.835
- feature: openapi-export
  check: operations_operation_ids
  layer: composite
  conditional: true
  condition: >-
    Only if the provider set an operationName on every method; nothing fetched shows the export inventing
    one.
  catalog_pass_rate: 0.827
  facet: contract_quality
  points: 4
  baseline_pass_rate: 0.918
  saturated: true
  saturated_note: >-
    92% of providers with a contract, docs and a reference already earn this; the vendor cannot move it
    for most of its buyers.
- feature: portals
  check: portal_present
  layer: composite
  provider_must: >-
    Publish the portal (ideally on a custom domain) and declare it as a DeveloperPortal entry in apis.yml
    common[].
  catalog_pass_rate: 0.228
  facet: developer_ergonomics
  points: 4
  baseline_pass_rate: 0.633
- feature: portals
  check: api_reference_present
  layer: composite
  provider_must: Declare the generated product REST endpoint pages as an APIReference entry in apis.yml
    common[].
  catalog_pass_rate: 0.222
  facet: developer_ergonomics
  points: 3
  baseline_pass_rate: 0.942
  saturated: true
  saturated_note: >-
    94% of providers with a contract, docs and a reference already earn this; the vendor cannot move it
    for most of its buyers.
- feature: portal-try-it
  check: console_or_sandbox
  layer: composite
  provider_must: Declare the portal Try It as a Console entry in apis.yml common[].
  catalog_pass_rate: 0.089
  facet: developer_ergonomics
  points: 3
  baseline_pass_rate: 0.332
- feature: agentcore-mcp-target
  check: mcp_server
  layer: agent_readiness
  grade: platform
  note: >-
    The MCP URL is the AgentCore Gateway's, on an AWS host, and every stage-to-tool translation is the
    same template — `platform` (0.25) in 0.22.0. Stages protected by Cognito or a Lambda authorizer cannot
    be targets at all.
  points: 12
  baseline_pass_rate: 0.22
earns_nothing:
- feature: throttling-usage-plans
  check: rate_limit_signal
  why: >-
    The throttling page describes a 429 and no rate-limit or Retry-After headers; there is nothing for
    the provider to declare in its contract short of adding headers itself.
- feature: throttling-usage-plans
  check: plans_present
  why: >-
    Usage plans are throttle/quota bundles bound to API keys in the console; nothing publishes them as
    a plan catalog on a public page.
- feature: portals
  check: sign_up_present
  why: >-
    Portal access is controlled only through Cognito user pools; the fetched pages describe sign-in to
    read the portal, not self-service key issuance, so a SignUp pointer would describe a login wall rather
    than onboarding.
out_of_reach:
  checks:
  - sdk_count_1
  - sdk_count_3
  - cli_present
  - idempotency
  - error_semantics
  - dry_run_mode
  - reversibility_documented
  - auth_clarity
  - delegated_identity
  - dynamic_client_registration
  - protected_resource_metadata
  - well_known_published
  - pricing_link
  - llms_txt_published
  - agent_card
  note: >-
    API Gateway serves no discovery or protected-resource documents on the provider's host, and pricing,
    SDKs, error envelopes and API behaviours are the provider's to publish.
unscored_practice:
- feature: openapi-export
  why: >-
    The export can embed x-amazon-apigateway-* integration extensions or Postman extensions; no check
    reads them, and integration extensions leak backend wiring that a provider should strip before publishing.
surface:
  contract_quality:
    reachable: 30.0
    total: 211
  developer_ergonomics:
    reachable: 10.0
    total: 42
  agent_readiness:
    reachable: 3.0
    total: 139
hard_rule: >-
  A model, not a score. Adopting this vendor changes a provider's Kin Score only when the provider publishes
  the resulting artifacts on its own surface; nothing here writes a score, and no sponsorship or partnership
  can.
method: searched
source:
- >-
  https://aws.amazon.com/blogs/compute/improve-api-discoverability-with-the-new-amazon-api-gateway-portal/
- https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html
- https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html
- https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-portals.html
- https://docs.aws.amazon.com/apigateway/latest/developerguide/mcp-server.html
measured:
  cohort:
    method: vendors-catalog.json detections (CNAME / header / URL shape / markup), never a name match
    detected: 0
    in_baseline: 0
  control:
    basis: providers earning contract_present + documentation_present + api_reference_present, minus the
      cohort
    n: 5216
  metric: >-
    cohort_pct / control_pct = mean share of the check's points earned (derived and platform credit weighted),
    x100
  measured_on: '2026-09-25'
  status: 'not measurable: 0 detected customers clear the baseline (need 20)'
simulation:
  simulated_on: '2026-09-25'
  rubric: 0.23.0
  population: providers publishing a contract (contract_present earned), replayable exactly
  providers: 8977
  providers_unreplayable: 987
  providers_moved: 8761
  conditional_rows: excluded (they depend on what the API already does)
  composite_lift:
    median: 3.3
    p75: 4.7
    p90: 5.2
    max: 8.3
    mean_among_movers: 3.3
  agent_readiness_lift:
    median: 2.1
    p75: 2.2
    p90: 2.2
    max: 2.6
    mean_among_movers: 2.2
  facet_lift_median_among_movers:
    contract_quality: 2.0
    developer_ergonomics: 16.6
  composite_band_moves:
    thin -> developing: 1201
    developing -> strong: 431
    emerging -> thin: 299
    strong -> exemplar: 95
    minimal -> emerging: 3
  agent_readiness_band_moves:
    agent-aware -> agent-ready: 639
    agent-ready -> agent-native: 68
  method: >-
    each provider's own kin/checks file, the vendor's maps at their stated credit, the scorer's composite
    formula; from -> to, nothing written