Rest Api

Rest Api nodes create endpoints for receiving HTTP requests. When requests are received a message is output to a connected Function node.

Only one Function node may be connected to the output port. The connected Function node returns a response to be sent back for the HTTP request.

Message Formats

Output

When an HTTP request is received, the Rest Api node outputs a message containing all the details of the request.

Field Type Description
method string Method of the request. Example: GET
pathname string Path of the request, excluding query string. Example: /users/5
endpoint string Resource endpoint matching the path of the request. Example: /users/{id}
resourceParams Object Map of resource parameter values. Example: {"id": "5"}
query Object Map of decoded query string parameter values. Example: {"admin": "true"}
headers Object Map of request header values. Example: {"Host": "stacks.stackery.io", "Accept": "application/json"}
body Buffer Request body.
ip string IP Address of requesting client. Example: 38.182.58.3
requestId string Request ID as a GUID. Example: a0a5150b-a050-11e6-895a-159872556d76

Expected Response

The response message from the connected Function node contains the HTTP response information.

Field Type Default Description
statusCode number 200 if body provided, else 204 Status code of the response. Example: 202
headers Object {} Map of response header values. Example: {"Content-Type": "text/html", "Access-Control-Allow-Origin": "example.com"}
body Buffer or string null Body of response. See notes about character encodings.

Settings

Name

A label for the node in the canvas.

Endpoint

A specification for the paths that will be handled by this request node. The value can define a single path, a path with resource parameters, and/or a wildcard (*).

Examples:

/users
/users/{id}
/users/{id}/{property}
/users/{id}/emails/{email}
/users/{id}/locations/*

When a request matches an endpoint with resource parameters, the value of the parameters will be provided in the resourceParams field of the request message. For example, a request made to /users/5/locations/US/OR/97205/9584-Oak-Leaf-Rd would have the following request message fields:

{
  ...
  "pathname": "/users/5/locations/US/OR/97205/9584-Oak-Leaf-Rd",
  "endpoint": "/users/{id}/locations/*",
  "resourceParams": {
    "id": "5",
    "*": "US/OR/97205/9584-Oak-Leaf-Rd"
  }
}

Use Custom Domain?

By default, Stackery will automatically create one domain for all the Rest Api nodes in the stack. This domain will be hosted under stackery-stacks.io.

You can also set a custom domain for each Rest Api node. The same custom domain can be shared across multiple Rest Api nodes as long as the endpoints do not overlap.

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 node in the canvas area. 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.

Limitations

As with all limitations, we continually work to remove them from Stackery. If you have any questions or concerns, don’t hesitate to reach out to us at support@stackery.io.

Timeout

HTTP requests have a maximum length of 30 seconds. If a connected function does not respond within this timeframe, the client will receive an HTTP 502 Bad Gateway response.

Request and Response Body Encoding

Request and response bodies must be unicode-compatible. Bodies that are not unicode-compatible will silently be modified to convert incompatible characters into compatible characters, but this process mangles the data.

Consider the following work-arounds:

  • Encode the data before transmission. Binary data can be encoded using common encodings like Base64 and Z85.
  • Store content in a storage service like Amazon Web Services S3 and use pre-signed URLs within HTTP redirect responses to have clients transparently operate with the storage service.

HTTP Compression

The limitation on response body encoding also means responses cannot be compressed using HTTP Compression. The Rest Api node removes Accept-Encoding headers from requests to ensure frameworks used in connected Function nodes do not attempt to compress responses.

Try Stackery For Free

Gain control and visibility of your serverless operations from architecture design to application deployment and infrastructure monitoring.