Skip to main content

Gateway Lambda

The Gateway Lambda endpoint is available inside the Depot environment. It can be called from any place that is authenticated and allowed (via an IAM statement) to execute it. Typically, this means any place in the same account/environment (for convenience).

info

The AWS Lambda runtime takes care of jumping from the client's network (as long as that client is able to reach the AWS Lambda runtime) to the Depot Vpc where Depot's Gateway Lambda executes.

tip

When you can, please consider using the Depot Lambda Client library to simplify your interactions with the Gateway Lambda.

API​

The payload of the Gateway Lambda is a JSON object with the following structure:

export class LambdaRequest {
  schema?: string;
  operation: keyof typeof Operation;
  dataset?: { id: string };
  expand?: string[];
  id?: string;
  data?: any;
  link?: string;
  sort?: string;
  limit?: number;
  filter?: string;
  stats?: string[];
  nextToken?: string;
  create?: boolean;
  mode?: string;
  version?: number;
  actions?: { readonly [actionKey: string]: LambdaRequest };
}

Unitary Operations​

create​

The following fields are required:

const createReq = {
  
}

get​

The following fields are required:

const getReq = {
    schema: "MySchema",
    id: "my-instance-id",
    operation: "get",
    dataset: { id: "my-dataset-id" },
}

The response is either { status: { code: 404 } } or the payload.data field contains the instance retrieved from Depot.

create​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "create",
    data: { /* my object */},
    dataset: { id: "my-dataset-id" },
}

The response is either { status: { code: 403 } } or the payload.data field contains the instance retrieved from Depot, with any auto-allocated or expanded field values filled in (e.g. id).

It is invalid to attempt to create something with an already existing id.

update​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "update",
    id: id,
    data: { /* my object */},
    dataset: { id: "my-dataset-id" },
    create: false | true | undefined,
}

The response is either { status: { code: 404 } } or the payload.data field contains the instance retrieved from Depot, with any auto-allocated or expanded field values filled in.

The id field is mandatory and must be identical between the request.id and request.data.id fields.

Mandatory fields must be provided within data; it is possible to omit fields marked as required: false. All fields are updated, legally absent fields are considered undefined and stored as such (typically as NULL in an SQL database).

The create field is optional (defaults to true).
When create = true then the operation assumes UPSERT semantics.
When create = false and the underlying entity is absent then it is treated as a 404.

patch​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "patch",
    id: id,
    data: { /* my object, can be partial */},
    dataset: { id: "my-dataset-id" },
}

The response is either { status: { code: 404 } } or the payload.data field contains the instance retrieved from Depot, with any auto-allocated or expanded field values filled in.

The id field is mandatory and must be identical between the request.id and request.data.id fields. It is permissible to omit any field, including mandatory fields. Absent fields are ignored and left unchanged.

get​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "get",
    id: id,
    dataset: { id: "my-dataset-id" },
}

The response is either { status: { code: 404 } } or the payload.data field contains the instance retrieved from Depot, with any auto-allocated or expanded field values filled in.

It is possible to request the expansion of fields beyond the main schema (e.g. reference fields, linked fields) using the expand field.

delete​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "delete",
    id: id,
    dataset: { id: "my-dataset-id" },
}

The response is either { status: { code: 404 } } or the { status: {code: 200 }}.

eval​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "eval",
    data: { /* my object */},
    dataset: { id: "my-dataset-id" },
}

The response's payload.data field contains the value sent by the client in the request.data field, augmented with values that Depot could compute (expression fields, transients, etc.)

It is guaranteed that this operation causes no alteration on the underlying database. It does not check nor imply that the object referenced by request.data.id exists prior to or after this call.

warning

When the id field is not provided by the client, the .eval() operation will only compute a value if the id field is of type expression. In particular, sequence id fields will be left undefined.

This may result in computing a hash value different that what would have been computed if an id was allocated (e.g. as part of a .create() operation).

list​

The following fields are required:

const getReq = {
    schema: "MySchema",
    operation: "list",
    id: id, 
    dataset: { id: "my-dataset-id" },
    filter: "field = 'value'", // optional
    sort: "field1,field2", // optional
    limit: 25, // optional
    nextToken: undefined, // optional
}

The response is either { status: { code: 404 } } or the { data: { items: [...], nextToken: 'someString' } }.

Only up to 25 items will be returned; if the result set is longer, the nextToken field will be defined. It is possible to request the next page by reissuing the list command with the last result.data.nextToken received and the same sort and filter parameters).

tip

This interface is not designed to perform batch operation, but rather to serve UI services that may require a few dozen items at a time.

The nextToken validity is not guaranteed beyond "a reasonable amount of time" (a few dozen seconds).

Responses​

The Payload of the response from the Gateway Lambda is a JSON object with the following contract:

interface LambdaGatewayResponse {
  status?: {
    code: number;
    message: string;
  };
  data?: any; // most frequently: an instance of what was returned
}

Batch Operations​

tip

This interface is not designed to perform batch operation, but rather to serve UI services that may require a few dozen items at a time. This facility is useful to perform together a few logically-connected operations to save on turnaround time.

The Batch operations use a special shape of request:


const batchReq = {
  dataset: { id: "my-dataset-id" },
  schema: "MySchema",
  operation: "batch",
  data: {
    batch: {
      action1: {
        create: { 
          schema: "MySchema",
          data: { /* my object */},  
        },
      },
      action2: {
        get: {
          schema: "MySchema",
          id: "my-instance-id",
        }
      },
      action3: {
        update: {
          schema: "MySchema",
          id: "my-next-instance-id",
          data: { /* my object */},  
        }
      }  
    }
  }  
}

The response (in case of success) is a JSON object with the following shape:

const response = {
  status: { code: 200 },
  data: {
    action1: { /* response of the create action */ },
      action2: { /* response of the get action */ },
      action3: { /* response of the update action */ },
  }  
}

The action1, action2, action3... are arbitrary keys that are used to link together the returned results with the original keys. They are client-allocated and not used beyond this specific call. They must be unique within the call.

The only supported batch actions are create, delete, update, get, eval