Skip to content
Code Genie
Blog

REST API

Code Genie provides a Serverless Express REST API hosted on AWS Lambda and API Gateway, utilizing the @codegenie/serverless-express package.

The API Gateway API is configured with an Authorizer attached to the Cognito User Pool to ensure only authenticated users have access.

Auth/Identity handler

Before running any of the core route logic, an Express handler takes the userId and email from event.requestContext.authorizer.jwt (provided by API Gateway) and stores them in req.cognitoUser. This allows the route logic to easily access key information about the caller.

Project Structure

  • Directorypackages
    • Directoryapi
      • Directoryroutes
        • apps.ts
        • me.ts
        • my-entities.ts 1 route per entity
      • README.md
      • app.local.ts
      • app.ts
      • constants.ts
      • jest.config.js
      • lambda.test.ts
      • lambda.ts
      • package-lock.json
      • package.json
      • try-parse-req.ts
      • tsconfig.json
      • types.d.ts
    • Directorycdk # see the Cloud Infrastructure guide for more details
      • Directorylib
        • Directoryconstructs
          • ExpressApi.ts

Entity API Routes

The REST API includes routes for each Entity defined in your Application Definition.

Example routes
# Top-level entities
/widgets # list
/widgets/:widgetId # individual


# Child entities
/widgets/:widgetId/related-widgets # list
/widgets/:widgetId/related-widgets/:relatedWidgetId # individual


# Grandchild entities
/related-widgets/:relatedWidgetId/deeply-related-widgets # list
/related-widgets/:relatedWidgetId/deeply-related-widgets/:deeplyRelatedWidgetId # individual

List API

Returns a list of records by calling the controller’s list* method. See the useList*Query hook and useSearch*Query hook in the frontend docs for Javascript examples.

Request
GET /widgets?lastEvaluatedKey=...&filter={}
Response
{
  "data": [{
    "widgetId": "a1b2c3",
    "name": "My Widget"
    ...
  }]
}

filter

The List API accepts a filter query string parameter that filters the results from the database before returning them to the client.

{
  "operator": "AND", // default: 'OR'
  "filters": [{
    "property": "name",
    "value": "search value"
  }]
}

lastEvaluatedKey

The List API returns a lastEvaluatedKey when there are additional pages of data. Provide this value as a query string parameter in the request to retrieve the next page.

See DynamoDB Pagination for more details.

Get API

Returns a single record by calling the controller’s get* method. See the useGet*Query hook in the frontend docs for Javascript examples.

Request
GET /widgets/:widgetId
Response
{
  "data": {
    "widgetId": "a1b2c3",
    "name": "My Widget"
    ...
  }
}

Create API

Creates a record with a unique id by calling the controller’s create* method. See the useCreate*Mutation hook in the frontend docs for Javascript examples.

Request
POST /widgets
{
  "widget": {
    "name": "My Widget"
  }
}
Response
{
  "data": {
    "widgetId": "a1b2c3",
    "name": "My Widget"
    ...
  }
}

Update API

Updates a record by calling the controller’s update* method. See the useUpdate*Mutation hook in the frontend docs for Javascript examples.

Request
PUT /widgets/:widgetId
{
  "widget": {
    "name": "My Widget"
  }
}
Response
{
  "data": {
    "widgetId": "a1b2c3",
    "name": "My Widget"
    ...
  }
}

Delete API

Deletes a record by calling the controller’s delete* method. See the useDelete*Mutation hook in the frontend docs for Javascript examples.

Request
DELETE /widgets/:widgetId
Response
{}