Introducing the Amazon API Gateway Integration!

Introducing the Amazon API Gateway Integration!

 

Deploy your API definition on the AWS API Gateway, straight from SwaggerHub!

The last few years have brought a gradual shift towards serverless Infrastructure. Infrastructure-as-a-Service (IaaS) has changed the landscape bringing low cost, agility, scalability and reliability to the mix. With no extra work needed around managing and maintaining services, it only made sense that the next big Integration that SwaggerHub introduced would be with a serverless API Gateway service. The Amazon API Gateway is one such service which needs no introduction. It is a fully managed platform which allows users to build, deploy and manage APIs at any scale. The important aspect of the Amazon API Gateway is that it supports the Swagger definition format for designing and building RESTful APIs, and as you know, SwaggerHub is all about the Swagger! AWS - SH Life could be so much easier if a developer could use the best tooling available to design the API, from API mocks to the dynamic capabilities of a robust API Editor, and deploy it to the AWS API Gateway, while eliminating the often complex configurations that are needed between the definitions and the Lambda functions. This is where SwaggerHub’s latest Amazon Gateway Integrations helps. With the Amazon Gateway Integrations, you could expose your API on the Amazon Gateway for consumption, quickly and automatically. Serverless deployment is also taken care of, with SwaggerHub auto-generating the building blocks of your API code in Amazon Lambda from the Swagger definition of SwaggerHub!

SwaggerHub has two API Gateway Integrations available –

  • Amazon API Gateway
  • Amazon API Gateway Lambda Sync

These Integrations are found in the top right corner of the API. Manage integration

Amazon API Gateway

The Amazon API Gateway allows users to quickly deploy their API on the Amazon Gateway in proxy mode, which allows the Amazon API Gateway to handle things like authentication, rate limiting, etc. SwaggerHub will keep the Gateway definition in sync with your API definition. Users can configure the Integration based on their needs. The following fields can be customized:

  • Name: The name of the Integration, which will be shown in SwaggerHub
  • AWS Region: The region which supports the AWS Gateway. Note, not all AWS regions listed support the Gateway, please consult the AWS documentation
  • API ID: The ID of the API to publish to. Leaving this field empty will create a new one on the AWS Gateway if it is not matched by the title of the API definition
  • Publish Mode: Dictates if the Integration should merge or overwrite the changes in the API on SwaggerHub with the one on the AWS Gateway if it already exists on the Gateway
  • Base Path Mode: The API Gateway has several ways to express a resource’s path, there are three options for interpreting the basePath property - Ignore, Prepend and Split. More details can be found here
  • Deployment Mode: Allows users to customize how the API is pushed to the Gateway. Users can “push on save” or disable the integration altogether. There are cases where users would not want to push the API to the Gateway on every instance the save is clicked, which is when choosing never on the Deployment Mode would help.
  • Address of the Server to Proxy to: This allows users to connect a custom API to an AWS service.
  • AWS Access and Secret Keys: The keys required to authorize SwaggerHub to connect to the API Gateway. More details can be found here

API Gateway Once configured, the API can now be deployed and synced with the AWS Gateway, all from SwaggerHub!

Amazon API Gateway Lambda Sync

AWS Lambda helps users build the backend logic to their services without the hassle of managing servers. The Amazon API Gateway and Lambda functions work well as complimentary services. The API Gateway enables the web-client to call the Lambda functions dynamically. The Lambda Sync Integration does the complicated plumbing for you on the Gateway, meaning users will only have to worry about the true business value of the app. The Integration can be configured to the needs of the user.

  • Name: The name of the Integration
  • AWS Region: The region which supports the AWS Gateway
  • API ID: The ID of the API to publish to. Leaving this field empty will create a new one on the AWS Gateway if one does not exist by matching the Swagger definition title value
  • Publish Mode: Dictates if the Integration should merge or overwrite the changes in the API on SwaggerHub with the one on the AWS Gateway if it already exists on the Gateway
  • Base Path Mode: The API Gateway has several ways to express a resource’s path. There are three options for interpreting the basePath property - Ignore, Prepend and Split. More details can be found here
  • Deployment Mode: Allows users to customize how the API is pushed to the Gateway. Users can “push on save” or disable the integration altogether. There are cases where users would not want to push the API to the Gateway on every instance the save is clicked, which is when choosing never on the Deployment Mode would help.
  • Execution role for creating non-existing Lambda functions: This dictates how SwaggerHub should create the Lambda functions.
  • AWS Access and Secret Keys: The keys required to authorize SwaggerHub to connect to the API Gateway. More details can be found here

API Gateway Lambda Once configured, the API design can now be deployed and synced with Amazon Lambda functions. Lambda functions are created and matched by the operationId in each operation. If you do not have an operationId (they are optional in the OpenAPI Specification), one will be created for you. If a lambda function exists with the same name as the operationId, it will be used, and a new function will not be created.

Additional Notes

In both proxy and lambda mode, SwaggerHub will add, if they do not exist, Amazon-specific extensions to the Swagger definition for every operation. These dictate how the API Gateway will be configured. If SwaggerHub sees that the extensions already exist, it will not modify them. Thus if you make changes to your definition and need to update the mapping to the AWS Gateway, you should delete the extension before saving. The Amazon API Gateway does not support every feature of the Swagger definition. SwaggerHub will attempt to disable unsupported features from your definition upon save–it will mark them as such in your definition. Since the features of the Amazon API Gateway are constantly being improved, please consult the Amazon documentation for a list of limitations. These two Integrations are powerful tools to take your API from design to deployment in the most efficient way possible using the AWS API Gateway.

To see the Integration in action, check out this short screencast!

Try it out today at SwaggerHub! If you have any suggestions for new Integrations or want to see your product integrated with SwaggerHub, give us a shout out with a feature request here.