Skip to content

rest-api-overview.md

Latest commit

 

History

History
82 lines (60 loc) · 3.43 KB

rest-api-overview.md

File metadata and controls

82 lines (60 loc) · 3.43 KB
Raw

Sleeper REST API

Sleeper exposes a REST API for interacting with a deployed instance over HTTPS. The API is an optional, in-progress feature: only the "add table" endpoint is available today, and more will follow.

The API is provisioned by the CDK RestApiStack and fronted by an AWS API Gateway v2 HTTP API backed by a single Lambda function. This page covers how to deploy it, find the invoke URL, authenticate against it, and where to look for the machine-readable contract.

Contents

Deploying the REST API stack

RestApiStack is one of Sleeper's optional CDK nested stacks. Enable it by adding RestApiStack to the sleeper.optional.stacks instance property alongside any other stacks you want deployed:

sleeper.optional.stacks=CompactionStack,IngestStack,QueryStack,RestApiStack

Then deploy the instance as normal. See the instance configuration guide for the list of optional stacks, and the CDK deployment guide for the full CDK workflow.

There are no REST-API-specific instance properties to set; the stack takes its configuration from the shared instance properties.

Finding the invoke URL

Once the stack is deployed, the API's invoke URL is available in two places:

  • CDK output RestApiUrl, printed at the end of a cdk deploy and visible in the CloudFormation console.
  • Instance property sleeper.rest.api.url, written back to the Sleeper instance configuration by the CDK. You can retrieve it with adminClient.sh or by reading the instance config directly from S3.

The URL has the form https://<apiId>.execute-api.<region>.amazonaws.com. Append the endpoint path (for example /sleeper/tables) to make a request.

Authentication

The API uses AWS IAM (Signature Version 4) for authentication. Every request must be signed with credentials belonging to an IAM identity that has the execute-api:Invoke permission on the API.

The minimum policy statement is:

{
  "Effect": "Allow",
  "Action": "execute-api:Invoke",
  "Resource": "arn:aws:execute-api:<region>:<account-id>:<api-id>/*/*/*"
}

Replace <api-id> with the id from the invoke URL (the subdomain part).

Any AWS SDK will sign requests automatically once you provide credentials. From the command line, curl's built-in --aws-sigv4 flag (curl 7.75+, shipped with the Sleeper Builder container) signs requests without any extra tooling; see add-table.md for a full example. awscurl is a slightly shorter alternative that also picks up session tokens automatically. Unsigned requests are rejected by the API Gateway IAM authorizer with a 403.

Endpoints

Method Path Purpose Docs
POST /sleeper/tables Create a table in a Sleeper instance add-table.md

More endpoints will be added over time. Existing scripts (see the tables documentation) remain the fuller way to manage a Sleeper instance.