3.2.1

REST API

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, and API Gateway API serves as the single entry point for your backend.

Key Features of API Gateway include:

  • Secure and deliberate access to your API's
  • Ability to host multiple versions and stages of your API
  • Exposes your HTTP endpoints, Lambda functions, or other AWS services to users
  • 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 a REST API:

  • Function

Configurable Properties

Display Name

Human readable name for this resource that is displayed on the Stackery Dashboard and Stackery CLI output.

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 it's place when the updated stack is deployed.

Routes

A REST API supports the following HTTP request methods:

  • GET
  • PUT
  • POST
  • DELETE
  • HEAD
  • *

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, Stackery automatically provisions a subdomain for you under stackery-stacks.io. 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

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

← PubSub TopicSecrets →