Publish APIs For Your Customers: Deploy Serverless Developer Portal For Amazon API Gateway

Amazon API Gateway is a fully managed service that allows you to create, secure, publish, test and monitor your APIs. We often come across scenarios where customers of these APIs expect a platform to learn and discover APIs that are available to them (often with examples).

The Serverless Developer Portal is one such application that is used for developer engagement by making your APIs available to your customers. Further, your customers can use the developer portal to subscribe to an API, browse API documentation, test published APIs, monitor their API usage, and submit their feedback.

This blog is a detailed step-by-step guide for deploying the Serverless Developer Portal for APIs that are managed via Amazon API Gateway.

Advantages

The users of the Amazon API Gateway can be vaguely categorized as -

API Publishers — They can use the Serverless Developer Portal to expose and secure their APIs for customers which can be integrated with AWS Marketplace for monetary benefits. Furthermore, they can customize the developer portal, including content, styling, logos, custom domains, etc.

API Consumers — They could be Frontend/Backend developers, third party customers, or simply students. They can explore available APIs, invoke the APIs, and go through the documentation to get an insight into how each API works with different requests.

Developer Portal Architecture

We would need to establish a basic understanding of how the developer portal works. The Serverless Developer Portal is a serverless application built on microservice architecture using Amazon API Gateway, Amazon Cognito, AWS Lambda, Simple Storage Service and Amazon CloudFront.

The developer portal comprises multiple microservices and components as described in the following figure.

Developer portal
Source: AWS

There are a few key pieces in the above architecture -

Let’s move forward to building and deploying a simple Serverless Developer Portal.

Building Your API

Start with deploying an API which can be accessed using API Gateway from

If you do not have any such API available, create a simple application by jumping to the section, “API Performance Across the Globe,” on this blog.

Setup custom domain name

For professional projects, I recommend that you create a custom domain name as they provide simpler and more intuitive URLs you can provide to your API users.

Make sure your API Gateway domain name is updated in the Route53 record set created after you set up your custom domain name.

See more on Setting up custom domain names for REST APIs — Amazon API Gateway

Enable CORS for an API Resource

There are two ways you can enable CORS on a resource:

Let’s discuss the easiest way to do it using a console.

Once enabled, you can see a mock integration on the OPTIONS method for the selected resource. You must enable CORS for ${proxy} resources too.

To verify the CORS is enabled on API resource, try curl on OPTIONS method

You should see the response OK in the header:

Deploy Developer Portal

There are two ways to deploy the developer portal for your API.

Using SAR

An easy way will be to deploy api-gateway-dev-portal directly from AWS Serverless Application Repository.

Note -If you intend to upgrade your Developer portal to a major version then you need to refer to the Upgrading Instructions which is currently under development.

Using AWS SAM

Parameters you must configure and verify includes:

  • ArtifactsS3BucketName
  • DevPortalSiteS3BucketName
  • DevPortalCustomersTableName
  • DevPortalPreLoginAccountsTableName
  • DevPortalAdminEmail
  • DevPortalFeedbackTableName
  • CognitoIdentityPoolName
  • CognitoDomainNameOrPrefix
  • CustomDomainName
  • CustomDomainNameAcmCertArn
  • UseRoute53Nameservers
  • AccountRegistrationMode

You can view your template file in AWS Cloudformation Designer to get a better idea of all the components/services involved and how they are connected.

See Developer portal settings for more information about parameters.

Note: Ensure that you have required privileges to make deployments, as, during the deployment process, it attempts to create various resources such as AWS Lambda, Cognito User Pool, IAM roles, API Gateway, Cloudfront Distribution, etc.

After your developer portal has been fully deployed, you can get its URL by following.

Create Usage Plan

Create a usage plan, to list your API under a subscribable APIs category allowing consumers to access the API using their API keys in the developer portal. Ensure that the API gateway stage is configured for the usage plan.

Publishing an API

API Gateway Developer Portal
Source: Github

3. Fill the registration form and hit Sign up.

Developer Portal Sign up

4. Enter the confirmation code received on your email address provided in the previous step.

5. Promote the user as Administrator by adding it to AdminGroup.
- Open Amazon Cognito User Pool console.
- Select the User Pool created for your developer portal.
- From the General Settings > Users and Groups page, select the User you want to promote as Administrator.
- Click on Add to group and then select the Admin group from the dropdown and confirm.

6. You will be required to log in again to log in as an Administrator. Click on the Admin Panel and choose the API you wish to publish from the APIs list.

Setting up an account

The signup process depends on the registration mode selected for the developer portal.

For request registration mode, you need to wait for the Administrator to approve your registration request.

For invite registration mode, you can only register on the portal when invited by the portal administrator.

Subscribing an API

  • Sign in to the developer portal.
  • Navigate to the Dashboard page and Copy your API Key.
  • Go to APIs Page to see a list of published APIs.
  • Select an API you wish to subscribe to and hit the Subscribe button.

Tips

  • When a user subscribes to API, all the APIs published under that usage plan are accessible no matter whether they are published or not.
  • Whenever you subscribe to an API, the catalog is exported from API Gateway resource documentation. You can customize the workflow or override the catalog swagger definition JSON in S3 bucket as defined in ArtifactsS3BucketName under /catalog/<ApiId>_<stage>.json.
  • For backend APIs, CORS requests are allowed only from custom domain names selected for your developer portal.
  • Ensure to set the CORS response header from the published API in order to invoke them from the developer portal.

Summary

You’ve seen how to deploy a Serverless Developer Portal and publish an API. If you are creating a serverless application for the first time, you might want to read more on Serverless Computing and AWS Gateway before you get started.

Start building your own developer portal. To know more on distributing your API Gateway APIs to your customers follow this AWS guide.

Originally published at https://www.velotio.com.