Amazon API Gateway Integration

Amazon API Gateway allows developers to create, publish, monitor and secure APIs at any scale. Using API Gateway, you can map HTTP endpoints to various backend services without developing and maintaining an infrastructure to handle authorization, access control, rate limiting and monitoring.

You can connect your API definitions in SwaggerHub to API Gateway by using the Amazon API Gateway integration. The integration will push your API definition to API Gateway every time you save it in SwaggerHub. This way you can quickly create or update an API in API Gateway from SwaggerHub.

Video tutorial

Difference between API Gateway integration and Lambda Sync

Amazon API Gateway can work in the proxy mode passing requests to an external API server, or it can use AWS Lambda functions as a backend for API endpoints. SwaggerHub has different integrations for these scenarios:

Amazon API Gateway (described in this topic) – Use it if you have an existing API server and you want to proxy or secure it using API Gateway.
Amazon API Gateway Lambda Sync – Use it if you want to use AWS Lambda functions as a backend for your API.

Supported OpenAPI versions

This integration supports OpenAPI 2.0 and OpenAPI 3.0. SwaggerHub On-Premise users need v. 1.19.3 to use OpenAPI 3.0 definitions with API Gateway.

Important

While Amazon API Gateway supports most of the OpenAPI 2.0 and 3.0 Specifications, it does not support some features (such as discriminator). See the known limitations below, and make sure your API definition uses only the features supported by Amazon API Gateway.

How the integration works

Once you enable API Gateway integration, SwaggerHub adds API Gateway extensions (x-amazon-apigateway-*) to your API definition spec. These extensions specify how your API will be configured in API Gateway. If your API definition already contains API Gateway extensions, SwaggerHub will not modify them.

Your API definition will be pushed to API Gateway every time you save it in the SwaggerHub editor.

If you are updating your API definition and need to update the mapping to API Gateway, you need to delete API Gateway-specific extensions before saving your API.

Notes:

API Gateway integration is one-way, which means your API definitions go from SwaggerHub to API Gateway, but not vice versa. You should edit and update your API definitions in SwaggerHub.
Like other SwaggerHub integrations, API Gateway integration is tied to a specific version of an API. If your API has multiple versions, you can configure the integration separately for different versions.

Step 1. Configure access to Amazon API Gateway

To be able to push to Amazon API Gateway, SwaggerHub needs access to AWS and a secret key with appropriate permissions.

Sign in to the Amazon AWS console at https://aws.amazon.com/console/.
In the top right corner, under your username, click My Security Credentials.
If you do not see the My Security Credentials menu, then click Services in the AWS header, type iam into the search bar, and click IAM in the search results.
If a prompt appears, select Continue to Security Credentials.
On the left, select Users and click Add user.
Enter the user name (for example, SwaggerHubUser). For the Access type, select Programmatic access.
Click the image to enlarge it.
Click Next: Permissions.
Select Attach existing policies directly and select the check box next to AmazonAPIGatewayAdministrator.
Click the image to enlarge it.
Click Next: Tags.
(Optional) Add tags if you want to.
Click Next: Review, then Create user.
Important: Note down the Access key ID and Secret access key – this is the only time you see them. You will need to specify these keys in SwaggerHub.
Click the image to enlarge it.

Step 2. Configure Amazon API Gateway integration

Open your API page in SwaggerHub.
If the API has several versions, select the version you want to push to Amazon API Gateway.
If this version is publishedPublishing an API, unpublish it. Only unpublished APIs can be integrated with Amazon API Gateway.
Make sure the API definition meets AWS requirements (see above).
Click the API name, switch to the Integrations tab and click Add New Integrations:
Select Amazon API Gateway Integration from the list of integrations.
Enter integration parameters:
- Name – A display name for this integration.
- AWS Region – Select the AWS region where you want to publish your API or that contains the existing API you want to publish to.
- API ID – Leave it blank to create a new API in API Gateway. Alternatively, if you want to update an existing API in API Gateway, specify the API ID here or in the x-aws-api-id key at the root level of your API definition.
  Tip
  You can find API IDs on the APIs dashboard in the API Gateway console.
  Click the image to enlarge it.
- Publish Mode – Choose how to handle existing APIs in API Gateway:
  - merge –Merge changes: add new changes made in SwaggerHub to API Gateway. This can be useful, for example, if your API in API Gateway is split into multiple parts in SwaggerHub, and you want only to synchronize the changes in one of these parts. The items that exist in API Gateway but are not defined in SwaggerHub will not be changed.
  - overwrite – (Recommended) Overwrite the existing API in API Gateway with the definition from SwaggerHub.
- Base Path Mode – This option has effect if the API base path differs from /, for example:
```
# OpenAPI 3.0
servers:
  - url: https://example.com/api/v2    # Base path is /api/v2

# OpenAPI 2.0
basePath: /api/v2
```
  This option specifies whether to create API Gateway resource paths (endpoints) with or without the base path. The options are:
  - ignore
  - prepend
  - split
  Refer to the API Gateway documentation to learn how these options work.
  If the base path is / or is not provided, use ignore. If an OpenAPI 3.0 definition contains multiple servers, the integration uses the base path of the first server.
- Update definition with extensions – This option affects the way the integration handles the changes in your API definition, such as new parameters or renamed paths.
  - Disabled – The request and response mappings in API Gateway will be updated automatically based on the current paths and parameters in your API definition. API Gateway extensions (x-amazon-gateway-*) will not be added to your API definition, but if they exist, SwaggerHub will create mappings based on these extensions.
  - Enabled – SwaggerHub will add the x-amazon-gateway-* extensions to your API definition that contains the request and response mappings for API Gateway, and the integration will create mappings based on these extensions. Note that the extensions are never updated once they are created. For example, added or changed parameters will not be reflected here. To update the extensions (and the corresponding mappings in API Gateway), you will have to delete the extensions and save your API definition so that SwaggerHub can recreate them.
    If this option is enabled, SwaggerHub may also make changes to the API definition to make it compliant with the Amazon API Gateway limitations. This includes disabling the example and readOnly properties, removing xml keys, and simplifying model definition names. Disabled features will be wrapped into the x-disabled-for-amazon-gateway extension property.
- Deployment Mode – Must be on save. Here, “deployment” refers to the action of pushing the definition to API Gateway (it doesn’t refer to the AWS “Deploy API” action).
- Address of the Server to Proxy to – The back-end HTTP(S) endpoint to which API Gateway will proxy the requests. Do not add a forward slash at the end.
  Correct:
```
http://api.example.com/reports/v2
https://myapi.com
```
  Incorrect:
```
https://myapi.com/
```
  Typically, this should be the same value as the API base path specified in your API definition, that is, the server url in OpenAPI 3.0 or scheme://host/basePath in OpenAPI 2.0.
- AWS Access Key and AWS Secret Keys – The keys required to authorize SwaggerHub to connect to Amazon API Gateway. See above.
- Enabled – Enables or disables the integration.
Click Create and Execute. SwaggerHub will publish your API definition to API Gateway.
Click Done to close the integration settings.

Step 3. Push the API to Amazon API Gateway

SwaggerHub pushes your API to API Gateway every time you save the API in SwaggerHub. If there was a problem with pushing the API to API Gateway, you will see an error at the top of the SwaggerHub Editor.

To see your API in API Gateway:

Open the Amazon API Gateway console at https://console.aws.amazon.com/apigateway.
In the top right corner, select the region you have pushed to.
Click your API in the APIs list. The created or updated API has the same name as the info.title in your API definition.
Click the image to enlarge it.

Step 4. Test API proxy calls

API Gateway lets you test API calls by proxying them to the associated back-end server. To test an API call:

Select a method in the list, for example, /pet > /{petId} > GET. You will see the request and response mappings for that method.
Click the image to enlarge it.
Click Test.
Enter the parameters (if any) and click Test.
You will see the response from your back-end endpoint.
Click the image to enlarge it.

Step 5. Deploy the API on AWS

To be able to test the API externally, you need to deploy it:

Click Actions and select Deploy API.
Enter a name for the Deployment stage and click Deploy.
Click the image to enlarge it.
Note down the Invoke URL – it is the base path of your deployed API. It has the following format: https://{api_id}.execute-api.{region}.amazonaws.com/{stage_name}/.
Click the image to enlarge it.

Resource URLs are composed by appending the resource paths to the Invoke URL:

https://qixsvjkio7.execute-api.us-east-1.amazonaws.com/development/pet/5

https://qixsvjkio7.execute-api.us-east-1.amazonaws.com/development/pet/findByStatus?status=available

GET methods can be tested directly in the browser by pasting the resource URL to the browser’s address bar. Other methods can be tested by using the cURL command-line tool or by using API testing tools like SoapUI.

Disable API Gateway integration

If you no longer want to push your API definition to Amazon API Gateway, you can do any of the following:

Disable the integration by unchecking the Enable check box in the integration parameters.
Set Deployment Mode to never in the integration parameters (this has the same effect as disabling the integration).
Delete the integration.

Your existing API will remain in Amazon API Gateway, but SwaggerHub will not update it anymore.

Limitations

The following limitations apply when importing OpenAPI definitions to Amazon API Gateway. Please note that these are the specifics of the Amazon API Gateway platform, not of SwaggerHub.

Amazon API Gateway known issues.
Query and header parameter names can contain only the following characters: A-Z a-z 0-9 - . _ $.
Models with circular references are not supported.
default responses are imported as 200 responses, unless the operation has a 200 response definition (in this case, the default response is ignored).
Additional considerations for OpenAPI 2.0:
- Form parameters (in: formData) are not supported and are ignored.
Additional considerations for OpenAPI 3.0:
- Cookie parameters (in: cookie) are not supported and are ignored.
- Response code ranges (4XX) are not supported. Use specific response codes instead.
- TRACE operation definitions are not supported. Use the x-amazon-apigateway-any-method extension to handle TRACE operations.

SwaggerHub will try to disable some unsupported keywords in your API definition by wrapping them into the x-disabled-for-amazon-gateway extension property. However, we recommend that you review your API definition manually and modify it to make it compatible with AWS.