REST API

This REST API resource implements the first version of AWS API Gateway REST APIs. Most new APIs should be implemented with the HTTP API resource instead. HTTP APIs have lower cost, have lower latency, and more easily integrate with OpenID authentication mechanisms. For a detailed comparison of the two resource types see Choosing Between HTTP APIs and REST APIs in the AWS API Gateway documentation.

Resource Overview

A REST API is used to define how users communicate with the resource that make up your serverless application. It represents an application programming interface (API) declared with Amazon API Gateway, a service that supports creation, deployment, and management of RESTful APIs. In a serverless architecture, an API Gateway API serves as an entry point for your backend.

Key Features of API Gateway include:

• Secure and deliberate access to resources
• Pay-as-you-go; Only pay for API calls you receive and the amount of data transferred out
• Authorization and access control, version management, and monitoring provided by AWS on your behalf

More specifically, a REST API allows you to declare a collection of API Gateway resources and methods that can be invoked through HTTPS endpoints. You're able to follow REST guidelines to add HTTP request methods and their respective paths as well as define a custom domain for users to access your API.

Event Subscription

Event subscription wires (solid line) visualize and configure event subscription integrations between two resources.

The following resources can be subscribed to REST API routes:

• Function
• State Machine

When a State Machine is subscribed to a route, the method should be POST. The body of the request is given to the State Machine as its input document.

Configurable Properties

Logical ID

The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in template.yaml or while viewing a stack in Template View mode.

The Logical ID of all sub-resources associated with this REST API will be prefixed with this value.

The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.

Default Logical ID Example: Api2

IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in its place when the updated stack is deployed.

Routes

A REST API supports the following HTTP request methods:

• GET
• PUT
• POST
• DELETE
• HEAD
• ANY (Allows for any of the above methods)

Enable CORS

Enable Cross Origin Resource Sharing (CORS) to allow browsers access to this REST API.

CORS Access Control Headers

Provide configurations, including origins, methods, or headers, that are allowed on requests sent to this REST API.

Visit the CORS section of AWS SAM's documentation for configuration options, or use * (most common) to indicate CORS requests are allowed from any domain.

Example CORS configuration:

  api3FEE112A:
    Type: AWS::Serverless::Api
    Properties:
      ...
      Cors:
        AllowOrigin: "'*'"
        AllowHeaders: "'*'"

Provision Custom Domain

By default, AWS automatically provisions a domain for you. When enabled, you're able to provide a custom domain to be used instead.

Custom Domain

The domain name that will host the API. AWS Certificate Manager will provision an SSL certificate for this domain. In order to provision the certificate, AWS will send an email to the domain's registration contacts and certain well-known domain administration email addresses:

• administrator@
• hostmaster@
• postmaster@
• webmaster@
• admin@

When deploying be sure to check these email addresses to approve the certificate. If the domain is not verified within one hour of the start of the deployment the deployment will fail and be rolled back automatically.

After deployment a CNAME DNS record will need to be created for the domain. Select the current deployment in the Stackery dashboard, then select the REST API on the Stackery Dashboard. Find and copy the DNS Name value in the properties panel on the right. Create a CNAME record to map the custom domain to this DNS name. Check with your DNS provider for instructions on how to create the record.

When using a custom domain, the Validation Domain field is required, and should be filled in with the top-level domain (i.e. if your domain is api.myapp.com, the validation domain would be myapp.com).

Private

Enable this setting to declare the REST API's endpoint as Private. If security and privacy are concerns when working with API Gateway requests, enabling this setting keeps requests from being routed out to the public internet. Requests travel through a secure, private network connection in AWS.

Visit the Private REST APIs section in the Virtual Network documentation to learn how resources in your Virtual Network can access a private REST API

Route

A REST API Route connected to a Function.

Double-click on the Route to configure the following properties:

Proxy To Existing HTTP Service

Check this box to proxy requests to this route to an existing REST API.

Routes may either proxy to an existing HTTP service or be connected to a Function. Enabling this setting will remove an existing event subscription to a Function.

HTTP Service Location

After enabling the Proxy to existing HTTP service setting, this setting provides the location of the existing REST API to route requests to.

If the route contains a wildcard "proxy" path variable, the variable can also be used for dynamic routing to the existing REST API. For example, a route's Path may be /users/{proxy+} with its HTTP Service Location set to https://abc.example.com/v1/users/{proxy}. This will cause a request to this API's /users/5/details.json path to be proxied to https://abc.example.com/v1/users/5/details.json.

IAM Permissions

When connected by a service discovery wire (dashed wire), a Function or Docker Task will add the following IAM policy to its role and gain permission to access this resource.

No Permissions Added

Environment Variables

When connected by a service discovery wire (dashed wire), a Function or Docker Task will automatically populate and reference the following environment variables in order to interact with this resource.

API_URL

The base URL used to access the API.

Example: https://a2t4in91ie.execute-api.us-west-2.amazonaws.com/development

Metrics & Logs

Double clicking a resource while viewing your stack's current deployment gives you access to your pre-configured resource properties, and links to the following metrics and logs.

• Response Metrics
• Response Time

Related AWS Documentation

AWS Documentation: AWS::Serverless::Api