MAAP API Query Service

Query Steps

1. Detect backend [lambda]
2. Route to appropriate handler for that backend [step function choice state]
3. Run query [lambda]
4. Write output to S3 bucket
   • If failure, write error to S3 bucket

Message Format

In JSON Schema;

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "src": {
      "type": "object",
      "Collection": {
        "description": "Collection object",
        "type": "object",
        "properties": {
          "ShortName": { "type": "string" },
          "Version": { "type": "string" }
        }
      }
    },
    "query": {
      "type": "object",
      "properties": {
        "fields": {
          "description": "Fields to be returned from dataset. If omitted, all fields will be returned",
          "type": "array",
          "items": { "type": "array" }
        },
        "bbox": {
          "description": "A GeoJSON-compliant 2D bounding box (https://tools.ietf.org/html/rfc7946#section-5)",
          "type": "array",
          "items": [
            { "type": "number", "description": "X Min" },
            { "type": "number", "description": "Y Min" },
            { "type": "number", "description": "X Max" },
            { "type": "number", "description": "Y Max" }
          ]
        }
      }
    }
  },
  "required": ["id", "src", "query"]
}

Development

SSM

In effort to avoid requiring that developers maintain a local copy of parameters for a Query Service environment, this project utilizes AWS SSM Parameter Store to manage such parameters.

To add a non-secret parameter:

aws ssm put-parameter --name /my/parameter --description "A parameter descripton" --type String --value "1234"

At time of writing, CloudFormation does not support SecureString SSM Parameters to be used as an environment variable.

To add a URL as a parameter:

aws ssm put-parameter --cli-input-json '{
  "Name": "/my/parameter",
  "Value": "http://myUrl.com",
  "Type": "String",
  "Description": "url"
}'

Alternatively, the web UI also supports URL values. See aws/aws-cli#2507 for more information.

Adding a Backend (AODS)

To add a new backend, a developer should first create a new handler. Backend handlers are intended to be simple, in charge of querying the data source and writing their results to S3. To simplify and unify the process of writing to S3, helper functions can be found in src/lib/s3.ts. It is important that each backend properly set the ContentType of the data uploaded, as end-users should be able to rely on this header to determine how to parse the result data.

After creating a handler, the developer should then update the RouteToBackendHandler step in the RunQuery State Machine found in template.yaml.