AWS Deep Dive

Amazon API Gateway

Continued notes about the Amazon API Gateway.

Working with REST APIs

Creating and Using Usage Plans with API Keys in API Gateway (Continued)

API keys can belong to multiple usage plans, and usage plans can be associated with multiple stages. But each API key can only be associated with one usage plan per stage.

Documenting REST APIs in API Gateway

Almost every relevant part of an API in API Gateway can have a DocumentationPart object associated with it; overall API documentation is then generated by collecting these objects. DocumentationPart objects are inherited within the API (except for documentation attached to RESOURCE, AUTHORIZER, and MODEL entities), but can then be overridden. API resource attachment is determined by the DocumentationPart object’s location attribute; patterns can be used here, in which case DocumentationPart objects are matched according to specificity.

Documentation itself is stored as a string-encoded JSON object; this object can have any structure, but it’s pretty clear that maximum mileage is obtained by using keys that are also used by the OpenAPI spec’s documentation. (No matter how API documentation is attached, it must be provided as JSON; the difference is that the API Gateway console accepts the appropriate JSON blob and string encodes it for you, while for the AWS CLI you must unsurprisingly provide the encoded object yourself.)

Documentation is published in an OpenAPI DocumentationVersion file that is tagged with a specific documentation version and associated with a specific stage. Note that once a DocumentationVersion snapshot is created, only its description can be updated. DocumentationVersion snapshots are specified by their version attribute (really an (API ID, version) tuple, but API ID will be constant for a given API).

The default API documentation export excludes documentation about integrations and authorizers, as this is generally internal-only. Interestingly, when exported documentation is both integrated directly into the appropriate parts of the API definition and grouped in the x-amazon-apigateway-documentation property. The reason for this duplication is that the x-amazon-apigateway-documentation property contains the provided JSON documentation objects in full, while integration into individual parts of the API definition is only done for documentation properties that match the OpenAPI spec. Thus, if only OpenAPI documentation properties (or x- extensions) are included in the documentation JSON blob, the x-amazon-apigateway-documentation property will be completely duplicative.

Documentation can be imported as well, but is expected to live in an x-amazon-apigateway-documentation property. Seems mostly useful when porting an API between two accounts (though in that case, why import the documentation separately?).

Generating an SDK for a REST API in API Gateway

SDKs must be regenerated whenever the API is redeployed (which makes sense, but also seems like kind of a drag…).

API Gateway has (IMHO) a somewhat brain-dead naming convention for exposed SDK functions based on the corresponding method’s path. Fortunately, API methods can be assigned an operationName (represented as operationId in Swagger - OpenAPI? - definition files) value that overrides this default.

A type property can also be assigned (both to the API method and its response) for use in strongly typed languages. Models can also be defined for SDKs, which allows them to be instantiated as objects (for languages that support this), rather than requiring developers to build and parse function input and output manually.