AWS API Gateway

This page documents how you can use AWS API Gateway with a running Spherical instance.

These instructions are for after you have already created a Spherical EC2 instance (and are largely taken from the instructions here).

Create an IAM Administrator User

As a best practice, you should also create an AWS Identity and Access Management (IAM) user with administrator permissions. Use that for all work that does not require root credentials. Create a password for console access, and access keys to use command line tools. For instructions, see Creating Your First IAM Admin User and Group in the IAM User Guide.

Create a REST API in the API Gateway Console

In this step, you create a simple REST API in the API Gateway console and attach the Spherical Lambda function to it as a backend.

  1. From the Services menu, choose API Gateway to go to the API Gateway console.

  2. If this is your first time using API Gateway, you see a page that introduces you to the features of the service. Choose Get Started. When the Create Example API popup appears, choose OK.

    If this isn't your first time using API Gateway, choose Create API.

  3. Under Choose the protocol, choose REST.

  4. Under Create new API, choose New API.

  5. Under Settings:

    • For API name, enter spherical-api.

    • If desired, enter a description in the Description field; otherwise, leave it empty.

    • Leave Endpoint Type set to Regional.

  6. Choose Create API.

  7. Under Resources, you'll see nothing but /. This is the root-level resource, which corresponds to the base path URL for your API (https://b123abcde4.execute-api.us-west-2.amazonaws.com/{stage-name}).

    From the Actions dropdown menu, choose Create Method.

  8. Under the resource name (/), you'll see a dropdown menu. Choose ANY and then choose the checkmark icon to save your choice.

  9. In the / – ANY – Setup pane, for Integration type, choose Lambda Function.

  10. Choose Use Lambda proxy integration.

  11. For Lambda Region, choose the Region where you created your Lambda function.

  12. In the Lambda Function field, type any character and then choose SphericalDefenceProxy-* (where * stands for the application ) from the dropdown menu. (If the dropdown menu doesn't appear, delete the character you just typed to make the dropdown menu appear.) Leave Use Default Timeout checked. Choose Save to save your choice.

  13. When the Add Permission to Lambda Function popup appears (saying "You are about to give API Gateway permission to invoke your Lambda function…"), choose OK to grant API Gateway that permission.

Now you'll see a / – ANY – Method Execution pane:

Deploy the REST API in the API Gateway Console

Once you complete Step 2, you've created an API, but you can't actually use it yet. This is because it needs to be deployed.

  1. From the Actions dropdown menu, choose Deploy API.

  2. From the Deployment stage dropdown menu, choose [New Stage].

  3. For Stage name, enter prod.

  4. Choose Deploy.

  5. In the prod Stage Editor, note the Invoke URL at the top. It should be in this format: (https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod). If you choose the Invoke URL, it will open a new browser tab with that URL.