AWS API Gateway OpenAPI Vendor Extensions

I was doing some work on the AWS API Gateway, and as I was going through their API documentation I found some of the OpenAPI vendor extensions they use as part of operations. These vendor extensions show up in the OpenAPI you export for any API, and reflect how AWS has extended the OpenAPI specification, making sure it does what they need it to do as part of AWS API Gateway operations.

AWS has 20 separate OpenAPI vendor extensions as part of the OpenAPI specification for any API you manage using their gateway solution:

  • x-amazon-apigateway-any-method - Specifies the Swagger Operation Object for the API Gateway catch-all ANY method in a Swagger Path Item Object. This object can exist alongside other Operation objects and will catch any HTTP method that was not explicitly declared.
  • x-amazon-apigateway-api-key-source - Specify the source to receive an API key to throttle API methods that require a key. This API-level property is a String type.
  • x-amazon-apigateway-authorizer - Defines a custom authorizer to be applied for authorization of method invocations in API Gateway. This object is an extended property of the Swagger Security Definitions object.
  • x-amazon-apigateway-authtype - Specify an optional customer-defined information describing a custom authorizer. It is used for API Gateway API import and export without functional impact.
  • x-amazon-apigateway-binary-media-types - Specifies the list of binary media types to be supported by API Gateway, such as application/octet-stream, image/jpeg, etc. This extension is a JSON Array.
  • x-amazon-apigateway-documentation - Defines the documentation parts to be imported into API Gateway. This object is a JSON object containing an array of the DocumentationPart instances.
  • x-amazon-apigateway-gateway-responses - Defines the gateway responses for an API as a string-to-GatewayResponse map of key-value pairs.
  • x-amazon-apigateway-gateway-responses.gatewayResponse - Defines a gateway response of a given response type, including the status code, any applicable response parameters, or response templates.
  • x-amazon-apigateway-gateway-responses.responseParameters - Defines a string-to-string map of key-value pairs to generate gateway response parameters from the incoming request parameters or using literal strings.
  • x-amazon-apigateway-gateway-responses.responseTemplates - Defines GatewayResponse mapping templates, as a string-to-string map of key-value pairs, for a given gateway response. For each key-value pair, the key is the content type; for example, “application/json”, and the value is a stringified mapping template for simple variable substitutions. A GatewayResponse mapping template is not processed by the Velocity Template Language (VTL) engine.
  • x-amazon-apigateway-integration - Specifies details of the backend integration used for this method. This extension is an extended property of the Swagger Operation object. The result is an API Gateway integration object.
  • x-amazon-apigateway-integration.requestTemplates - Specifies mapping templates for a request payload of the specified MIME types.
  • x-amazon-apigateway-integration.requestParameters - Specifies mappings from named method request parameters to integration request parameters. The method request parameters must be defined before being referenced.
  • x-amazon-apigateway-integration.responses - Defines the method’s responses and specifies parameter mappings or payload mappings from integration responses to method responses.
  • x-amazon-apigateway-integration.response - Defines a response and specifies parameter mappings or payload mappings from the integration response to the method response.
  • x-amazon-apigateway-integration.responseTemplates - Specifies mapping templates for a response payload of the specified MIME types.
  • x-amazon-apigateway-integration.responseParameters - Specifies mappings from integration method response parameters to method response parameters. Only the header and body types of the integration response parameters can be mapped to the header type of the method response.
  • x-amazon-apigateway-request-validator - Specifies a request validator, by referencing a request_validator_name of the x-amazon-apigateway-request-validators Object map, to enable request validation on the containing API or a method. The value of this extension is a JSON string.
  • x-amazon-apigateway-request-validators - Defines the supported request validators for the containing API as a map between a validator name and the associated request validation rules. This extension applies to an API.
  • x-amazon-apigateway-request-validators.requestValidator - Specifies the validation rules of a request validator as part of the x-amazon-apigateway-request-validators Object map definition.

I keep track of these vendor extensions as part of my OpenAPI toolbox, but I also like to aggregate them, and learn from them. They tell an important story of what AWS is looking to do with the AWS API Gateway. They point to some interesting use cases for the OpenAPI specification including validation, and transforming or mapping API requests and responses, to name a few. There is always a lot to learn from API providers who are extending the OpenAPI specification.

I encounter a number of API designers and architects who don’t know they can extend the specification. It is important that teams realize they can not just extend the specification to fit their needs, but also that they should be learning from how other API proviers are doing this. A few signs of an API provider who is further along in their API journey are 1) actively maintaining and sharing and OpenAPI definition for their APIs, and 2) actively extending and sharing the vendor extensions they use to make OpenAPI do exactly what they need.