Api

The cloud.Api resource represents a collection of HTTP endpoints that can be invoked by clients over the internet. APIs often serve as the front door for applications to access data, business logic, or functionality from your backend services.

The Api resource models an endpoint as a collection of routes, each mapped to an event handler function. A route is a combination of a path, like "/users/:userid" and a set of HTTP methods, like GET, POST, or DELETE. When a client invokes a route, the corresponding event handler function executes.

Usage

REST API

The following example shows a complete REST API implementation using cloud.Api, ex.Table & cloud.Counter

bring cloud;
bring ex;

let api = new cloud.Api();
// Used for generating unique id
let counter = new cloud.Counter();
// our employee database
let db = new ex.Table(
  name: "employees",
  primaryKey: "id",
  columns: {
    "name" => ex.ColumnType.STRING
  }
);

api.get("/employees", inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
  let result = MutJson [];
  let var i = 0;
  for employee in db.list() {
    result.setAt(i, employee);
    i = i + 1;
  }
  return cloud.ApiResponse {
    status: 200,
    body: Json.stringify(result)
  };
});


api.get("/employees/:id", inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
  let employee = db.get(request.vars.get("id"));
  return cloud.ApiResponse {
    status: 200,
    body: Json.stringify(employee)
  };
});

api.post("/employees", inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
   if let body = request.body {
    let employeeData = Json.parse(body);
    let id = "{counter.inc()}";
    db.insert(id, employeeData);
    return cloud.ApiResponse {
      status: 201,
      body: id
    };
   }
});

api.put("/employees/:id", inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
  if let body = request.body {
    let employeeData = Json.parse(body);
    let id = request.vars.get("id");
    db.update(id, employeeData);
    return cloud.ApiResponse {
      status: 200,
      body: Json.stringify(employeeData)
    };
  }
});

api.delete("/employees/:id", inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
  let id = request.vars.get("id");
  db.delete(id);
  return cloud.ApiResponse {
    status: 204
  };
});

Target-specific details

Simulator (`sim`)

The sim implementation of cloud.Api uses nodejs express.

AWS (`tf-aws` and `awscdk`)

The AWS implementation of cloud.Api uses Amazon API Gateway.

Azure (`tf-azure`)

🚧 Not supported yet (tracking issue: #625)

GCP (`tf-gcp`)

🚧 Not supported yet (tracking issue: #624)

API Reference

Api

Functionality shared between all Api implementations.

Initializers

bring cloud;

new cloud.Api(props?: ApiProps);

Name	Type	Description
`props`	`ApiProps`	No description.

`props`^Optional

Type: ApiProps

Methods

Preflight Methods

Name	Description
`connect`	Add a inflight handler to the api for CONNECT requests on the given path.
`delete`	Add a inflight handler to the api for DELETE requests on the given path.
`get`	Add a inflight handler to the api for GET requests on the given path.
`head`	Add a inflight handler to the api for HEAD requests on the given path.
`options`	Add a inflight handler to the api for OPTIONS requests on the given path.
`patch`	Add a inflight handler to the api for PATCH requests on the given path.
`post`	Add a inflight handler to the api for POST requests on the given path.
`put`	Add a inflight handler to the api for PUT requests on the given path.

`connect`

connect(path: str, inflight: IApiEndpointHandler, props?: ApiConnectOptions): void

Add a inflight handler to the api for CONNECT requests on the given path.

`path`^Required

Type: str

The path to handle CONNECT requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiConnectOptions

Options for the route.

`delete`

delete(path: str, inflight: IApiEndpointHandler, props?: ApiDeleteOptions): void

Add a inflight handler to the api for DELETE requests on the given path.

`path`^Required

Type: str

The path to handle DELETE requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiDeleteOptions

Options for the route.

`get`

get(path: str, inflight: IApiEndpointHandler, props?: ApiGetOptions): void

Add a inflight handler to the api for GET requests on the given path.

`path`^Required

Type: str

The path to handle GET requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiGetOptions

Options for the route.

`head`

head(path: str, inflight: IApiEndpointHandler, props?: ApiHeadOptions): void

Add a inflight handler to the api for HEAD requests on the given path.

`path`^Required

Type: str

The path to handle HEAD requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiHeadOptions

Options for the route.

`options`

options(path: str, inflight: IApiEndpointHandler, props?: ApiOptionsOptions): void

Add a inflight handler to the api for OPTIONS requests on the given path.

`path`^Required

Type: str

The path to handle OPTIONS requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiOptionsOptions

Options for the route.

`patch`

patch(path: str, inflight: IApiEndpointHandler, props?: ApiPatchOptions): void

Add a inflight handler to the api for PATCH requests on the given path.

`path`^Required

Type: str

The path to handle PATCH requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiPatchOptions

Options for the route.

`post`

post(path: str, inflight: IApiEndpointHandler, props?: ApiPostOptions): void

Add a inflight handler to the api for POST requests on the given path.

`path`^Required

Type: str

The path to handle POST requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiPostOptions

Options for the route.

`put`

put(path: str, inflight: IApiEndpointHandler, props?: ApiPutOptions): void

Add a inflight handler to the api for PUT requests on the given path.

`path`^Required

Type: str

The path to handle PUT requests for.

`inflight`^Required

Type: IApiEndpointHandler

The function to handle the request.

`props`^Optional

Type: ApiPutOptions

Options for the route.

Static Functions

Name	Description
`onLiftType`	A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
`renderCorsHeaders`	Generates an object containing default CORS response headers and OPTIONS response headers.
`renderOpenApiPath`	Converts input path to a valid OpenAPI path (replaces `:` based path params with `{}`).

`onLiftType`

bring cloud;

cloud.Api.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

`host`^Required

Type: IInflightHost

`ops`^Required

Type: MutArray<str>

`renderCorsHeaders`

bring cloud;

cloud.Api.renderCorsHeaders(corsOptions?: ApiCorsOptions);

Generates an object containing default CORS response headers and OPTIONS response headers.

`corsOptions`^Optional

Type: ApiCorsOptions

The CORS options to generate the headers from.

`renderOpenApiPath`

bring cloud;

cloud.Api.renderOpenApiPath(path: str);

Converts input path to a valid OpenAPI path (replaces : based path params with {}).

`path`^Required

Type: str

The path to convert (assumes path is valid).

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`url`	`str`	The base URL of the API endpoint.

`node`^Required

node: Node;

Type: constructs.Node

The tree node.

`url`^Required

url: str;

Type: str

The base URL of the API endpoint.

Structs

ApiConnectOptions

Options for Api patch endpoint.

Initializer

bring cloud;

let ApiConnectOptions = cloud.ApiConnectOptions{ ... };

ApiCorsOptions

Cors Options for Api.

Initializer

bring cloud;

let ApiCorsOptions = cloud.ApiCorsOptions{ ... };

Properties

Name	Type	Description
`allowCredentials`	`bool`	Whether to allow credentials.
`allowHeaders`	`MutArray<str>`	The list of allowed headers.
`allowMethods`	`MutArray<HttpMethod>`	The list of allowed methods.
`allowOrigin`	`str`	The allowed origin.
`exposeHeaders`	`MutArray<str>`	The list of exposed headers.
`maxAge`	`duration`	How long the browser should cache preflight request results.

`allowCredentials`^Optional

allowCredentials: bool;

Type: bool
Default: false

Whether to allow credentials.

`allowHeaders`^Optional

allowHeaders: MutArray<str>;

Type: MutArray<str>
Default: ["Content-Type", "Authorization"]

The list of allowed headers.

Example

["Content-Type"]

`allowMethods`^Optional

allowMethods: MutArray<HttpMethod>;

Type: MutArray<HttpMethod>
Default: [HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH, HttpMethod.DELETE, HttpMethod.HEAD, HttpMethod.OPTIONS]

The list of allowed methods.

Example

[HttpMethod.GET, HttpMethod.POST]

`allowOrigin`^Optional

allowOrigin: str;

Type: str
Default: "*"

The allowed origin.

Example

"https://example.com"

`exposeHeaders`^Optional

exposeHeaders: MutArray<str>;

Type: MutArray<str>
Default: []

The list of exposed headers.

Example

["Content-Type"]

`maxAge`^Optional

maxAge: duration;

Type: duration
Default: 300 seconds

How long the browser should cache preflight request results.

ApiDeleteOptions

Options for Api put endpoint.

Initializer

bring cloud;

let ApiDeleteOptions = cloud.ApiDeleteOptions{ ... };

ApiGetOptions

Options for Api get endpoint.

Initializer

bring cloud;

let ApiGetOptions = cloud.ApiGetOptions{ ... };

ApiHeadOptions

Options for Api patch endpoint.

Initializer

bring cloud;

let ApiHeadOptions = cloud.ApiHeadOptions{ ... };

ApiOptionsOptions

Options for Api patch endpoint.

Initializer

bring cloud;

let ApiOptionsOptions = cloud.ApiOptionsOptions{ ... };

ApiPatchOptions

Options for Api patch endpoint.

Initializer

bring cloud;

let ApiPatchOptions = cloud.ApiPatchOptions{ ... };

ApiPostOptions

Options for Api post endpoint.

Initializer

bring cloud;

let ApiPostOptions = cloud.ApiPostOptions{ ... };

ApiProps

Options for Api.

Initializer

bring cloud;

let ApiProps = cloud.ApiProps{ ... };

Properties

Name	Type	Description
`cors`	`bool`	Options for configuring the API's CORS behavior across all routes.
`corsOptions`	`ApiCorsOptions`	Options for configuring the API's CORS behavior across all routes.

`cors`^Optional

cors: bool;

Type: bool
Default: false, CORS configuration is disabled

Options for configuring the API's CORS behavior across all routes.

Options can also be overridden on a per-route basis. (not yet implemented) When enabled this will add CORS headers with default options. Can be customized by passing corsOptions

Example

true

`corsOptions`^Optional

corsOptions: ApiCorsOptions;

Type: ApiCorsOptions
Default: Default CORS options are applied when cors is set to true allowOrigin: "*", allowMethods: [ HttpMethod.GET, HttpMethod.POST, HttpMethod.PUT, HttpMethod.DELETE, HttpMethod.HEAD, HttpMethod.OPTIONS, ], allowHeaders: ["Content-Type", "Authorization"], exposeHeaders: [], allowCredentials: false,

Options for configuring the API's CORS behavior across all routes.

Options can also be overridden on a per-route basis. (not yet implemented)

Example

{ allowOrigin: "https://example.com" }

ApiPutOptions

Options for Api put endpoint.

Initializer

bring cloud;

let ApiPutOptions = cloud.ApiPutOptions{ ... };

ApiRequest

Shape of a request to an inflight handler.

Initializer

bring cloud;

let ApiRequest = cloud.ApiRequest{ ... };

Properties

Name	Type	Description
`method`	`HttpMethod`	The request's HTTP method.
`path`	`str`	The request's path.
`query`	`MutMap<str>`	The request's query string values.
`vars`	`MutMap<str>`	The path variables.
`body`	`str`	The request's body.
`headers`	`MutMap<str>`	The request's headers.

`method`^Required

method: HttpMethod;

Type: HttpMethod

The request's HTTP method.

`path`^Required

path: str;

Type: str

The request's path.

`query`^Required

query: MutMap<str>;

Type: MutMap<str>

The request's query string values.

`vars`^Required

vars: MutMap<str>;

Type: MutMap<str>

The path variables.

`body`^Optional

body: str;

Type: str

The request's body.

`headers`^Optional

headers: MutMap<str>;

Type: MutMap<str>

The request's headers.

ApiResponse

Shape of a response from a inflight handler.

Initializer

bring cloud;

let ApiResponse = cloud.ApiResponse{ ... };

Properties

Name	Type	Description
`body`	`str`	The response's body.
`headers`	`MutMap<str>`	The response's headers.
`status`	`num`	The response's status code.

`body`^Optional

body: str;

Type: str
Default: no body

The response's body.

`headers`^Optional

headers: MutMap<str>;

Type: MutMap<str>
Default: {}

The response's headers.

`status`^Optional

status: num;

Type: num
Default: 200

The response's status code.

CorsHeaders

Type definition for CORS headers which includes default and options headers.

Initializer

bring cloud;

let CorsHeaders = cloud.CorsHeaders{ ... };

Properties

Name	Type	Description
`defaultResponse`	`MutMap<str>`	Default CORS response headers.
`optionsResponse`	`MutMap<str>`	CORS options response headers.

`defaultResponse`^Required

defaultResponse: MutMap<str>;

Type: MutMap<str>

Default CORS response headers.

`optionsResponse`^Required

optionsResponse: MutMap<str>;

Type: MutMap<str>

CORS options response headers.

Protocols

IApiEndpointHandler

Extends: IInflight
Implemented By: IApiEndpointHandler

Inflight client: @winglang/sdk.cloud.IApiEndpointHandlerClient

A resource with an inflight "handle" method that can be passed to one of the Api request preflight methods.

IApiEndpointHandlerClient

Implemented By: IApiEndpointHandlerClient

Inflight client for IApiEndpointHandler.

Methods

Name	Description
`handle`	Inflight that will be called when a request is made to the endpoint.

`handle`

inflight handle(request: ApiRequest): ApiResponse?

Inflight that will be called when a request is made to the endpoint.

`request`^Required

Type: ApiRequest

Enums

HttpMethod

Allowed HTTP methods for a endpoint.

Members

Name	Description
`GET`	Get.
`HEAD`	Head.
`POST`	Post.
`PUT`	Put.
`DELETE`	Delete.
`CONNECT`	Connect.
`OPTIONS`	Options.
`PATCH`	Patch.

`GET`

Get.

`HEAD`

Head.

`POST`

Post.

`PUT`

Put.

`DELETE`

Delete.

`CONNECT`

Connect.

`OPTIONS`

Options.

`PATCH`

Patch.

Usage​

REST API​

Target-specific details​

Simulator (sim)​

AWS (tf-aws and awscdk)​

Azure (tf-azure)​

GCP (tf-gcp)​

API Reference ​

Api ​

Initializers ​

propsOptional ​

Methods ​

Preflight Methods​

connect ​

pathRequired ​

inflightRequired ​

propsOptional ​

delete ​

pathRequired ​

inflightRequired ​

propsOptional ​

get ​

pathRequired ​

inflightRequired ​

propsOptional ​

head ​

pathRequired ​

inflightRequired ​

propsOptional ​

options ​

pathRequired ​

inflightRequired ​

propsOptional ​

patch ​

pathRequired ​

inflightRequired ​

propsOptional ​

post ​

pathRequired ​

inflightRequired ​

propsOptional ​

put ​

pathRequired ​

inflightRequired ​

propsOptional ​

Static Functions ​

onLiftType ​

hostRequired ​

opsRequired ​

renderCorsHeaders ​

corsOptionsOptional ​

renderOpenApiPath ​

pathRequired ​

Properties ​

nodeRequired ​

urlRequired ​

Structs ​

ApiConnectOptions ​

Initializer ​

ApiCorsOptions ​

Initializer ​

Properties ​

allowCredentialsOptional ​

allowHeadersOptional ​

allowMethodsOptional ​

allowOriginOptional ​

exposeHeadersOptional ​

maxAgeOptional ​

ApiDeleteOptions ​

Initializer ​

ApiGetOptions ​

Initializer ​

ApiHeadOptions ​

Initializer ​

ApiOptionsOptions ​

Initializer ​

ApiPatchOptions ​

Initializer ​

ApiPostOptions ​

Initializer ​

Usage

REST API

Target-specific details

Simulator (`sim`)

AWS (`tf-aws` and `awscdk`)

Azure (`tf-azure`)

GCP (`tf-gcp`)

API Reference

Api

Initializers

`props`^Optional

Methods

Preflight Methods

`connect`

`path`^Required

`inflight`^Required

`props`^Optional

`delete`

`path`^Required

`inflight`^Required

`props`^Optional

`get`

`path`^Required

`inflight`^Required

`props`^Optional

`head`

`path`^Required

`inflight`^Required

`props`^Optional

`options`

`path`^Required

`inflight`^Required

`props`^Optional

`patch`

`path`^Required

`inflight`^Required

`props`^Optional

`post`

`path`^Required

`inflight`^Required

`props`^Optional

`put`

`path`^Required

`inflight`^Required

`props`^Optional

Static Functions

`onLiftType`

`host`^Required

`ops`^Required

`renderCorsHeaders`

`corsOptions`^Optional

`renderOpenApiPath`

`path`^Required

Properties

`node`^Required

`url`^Required

Structs

ApiConnectOptions

Initializer

ApiCorsOptions

Initializer

Properties

`allowCredentials`^Optional

`allowHeaders`^Optional

`allowMethods`^Optional

`allowOrigin`^Optional

`exposeHeaders`^Optional

`maxAge`^Optional

ApiDeleteOptions

Initializer

ApiGetOptions

Initializer

ApiHeadOptions

Initializer

ApiOptionsOptions

Initializer

ApiPatchOptions

Initializer

ApiPostOptions

Initializer