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.

Source: AWS

There are a few key pieces in the above architecture -

1. Identity Management: Amazon Cognito is basically the secure user directory of the developer portal responsible for user management. It allows you to configure triggers for registration, authentication, and confirmation, thereby giving you more control over the authentication process. 
2. Business Logic: AWS Cloudfront is configured to serve your static content hosted in a private S3 bucket. The static content is built using the React JS framework which interacts with backend APIs dictating the business logic for various events. 
3. Catalog Management: Developer portal uses catalog for rendering the APIs with Swagger specifications on the APIs page. The catalog file (catalog.json in S3 Artifact bucket) is updated whenever an API is published or removed. This is achieved by creating an S3 trigger on AWS Lambda responsible for studying the content of the catalog directory and generating a catalog for the developer portal.  
4. API Key Creation: API Key is created for consumers at the time of registration. Whenever you subscribe to an API, associated Usage Plans are updated to your API key, thereby giving you access to those APIs as defined by the usage plan. Cognito User - API key mapping is stored in the DynamoDB table along with other registration related details.
5. Static Asset Uploader: AWS Lambda (Static-Asset-Uploader) is responsible for updating/deploying static assets for the developer portal. Static assets include - content, logos, icons, CSS, JavaScripts, and other media files.

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 

CODE: https://gist.github.com/velotiotech/d2f47ea76ee05b1ee4ce18481725253e.js

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:

1. Enable CORS Using the Console
2. Enable CORS on a resource using the import API from Amazon API Gateway

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

1. Open API Gateway console.
2. Select the API Gateway for your API from the list.
3. Choose a resource to enable CORS for all the methods under that resource.
   Alternatively, you could choose a method under the resource to enable CORS for just this method.
4. Select Enable CORS from the Actions drop-down menu.
5. In the Enable CORS form, do the following:
   - Leave Access-Control-Allow-Headers and Access-Control-Allow-Origin header to default values.
   - Click on Enable CORS and replace existing CORS headers.
6. Review the changes in Confirm method changes popup, choose Yes, overwrite existing values to apply your CORS settings.

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

CODE: https://gist.github.com/velotiotech/fcef016bef1682b22d40af910591766f.js

You should see the response OK in the header:

CODE: https://gist.github.com/velotiotech/f8b3ba9e0cdca5437e16280e201aa8e4.js

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

1. Ensure that you have the latest AWS CLI and AWS SAM CLI installed and configured.
2. Download or clone the API Gateway Serverless Developer Portal repository.
3. Update the Cloudformation template file - cloudformation/template.yaml.

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.

4. Replace the static files in your project with the ones you would like to use.
   dev-portal/public/custom-content
   lambdas/static-asset-uploader/build
   - api-logo contains the logos you would like to show on the API page (in png format). Portal checks for an api-id_stage.png file when rendering the API page. If not found, it chooses the default logo - default.png.
   - content-fragments includes various markdown files comprising the content of the different pages in the portal. 
   - Other static assets including favicon.ico, home-image.png and nav-logo.png that appear on your portal. 

5. Let’s create a ZIP file of your code and dependencies, and upload it to Amazon S3. Running below command creates an AWS SAM template packaged.yaml, replacing references to local artifacts with the Amazon S3 location where the command uploaded the artifacts:

CODE: https://gist.github.com/velotiotech/528ff31d85c49529783b939aa2fd1811.js

6. Run the following command from the project root to deploy your portal, replace:
   - {your-template-bucket-name} with the name of your Amazon S3 bucket.
   - {custom-prefix} with a prefix that is globally unique.
   - {cognito-domain-or-prefix} with a unique string.

CODE: https://gist.github.com/velotiotech/80ffe156348081aff849522dca711e02.js

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.

1. Open the AWS CloudFormation console.
2. Select your stack you created above.
3. Open the Outputs section. The URL for the developer portal is specified in the WebSiteURL property.
   

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

Only Administrators have permission to publish an API. To create an Administrator account for your developer portal -

1. Go to the WebSiteURL obtained after the successful deployment. 

2. On the top right of the home page click on Register.

Source: Github

3. Fill the registration form and hit 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

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

Tips

1. When a user subscribes to API, all the APIs published under that usage plan are accessible no matter whether they are published or not.
2. 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</stage></apiid>. 
3. For backend APIs, CORS requests are allowed only from custom domain names selected for your developer portal.
4. 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.