Working with REST APIs

The REST API connector sends resource metadata to external REST endpoints. It supports all HTTP methods and works for both publishing and synchronization.

Prerequisites

Step types

The REST API connector supports the following step type.

Create this connector

Configuration

{
  "restConfig": {
    "apiBase": "https://api.example.com/v1",
    "securityConfig": {
      "type": "ApiKey",
      "secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-api-key"
    }
  },
  "fieldMappings": [
    { "source": "asset.assetId", "target": "externalId" },
    { "source": "asset.assetName", "target": "title" }
  ],
  "triggers": [
    {
      "description": "Create record in external system on asset creation",
      "resources": ["asset"],
      "events": ["create"],
      "stepType": "rest",
      "steps": [{
        "restConfig": {
          "method": "POST",
          "path": "/records"
        }
      }]
    },
    {
      "description": "Update record on asset update",
      "resources": ["asset"],
      "events": ["update"],
      "stepType": "rest",
      "steps": [{
        "restConfig": {
          "method": "PUT",
          "path": "/records/${project.connectedResource.externalId}"
        }
      }]
    },
    {
      "description": "Delete record on asset deletion",
      "resources": ["asset"],
      "events": ["delete"],
      "stepType": "rest",
      "steps": [{
        "restConfig": {
          "method": "DELETE",
          "path": "/records/${project.connectedResource.externalId}"
        }
      }]
    }
  ]
}

Configuration fields

The following table describes the configuration fields for the REST API connector.

Connector-level fields (restConfig)

Step-level fields

Connected resources

When a REST POST or PUT step creates or updates a record in an external system, SDMA automatically captures the external ID from the response. This stored ID is called a connected resource and you can reference it in subsequent steps.

How it works

Controlling the stored field name

Use responseFieldMapping in the step to control which response field SDMA captures and what name SDMA stores it under:

{
  "method": "POST",
  "path": "/records",
  "responseFieldMapping": [
    { "source": "id", "target": "project.externalRecordId" }
  ]
}

In this example, SDMA stores the id field from the API response as externalRecordId. You can then reference it as ${project.connectedResource.externalRecordId} in later steps.

Example

In the full configuration example above, the POST /records step creates a record. The external API returns a response containing an externalId field. SDMA stores this value automatically. The update and delete triggers then use ${project.connectedResource.externalId} in their paths to target the correct external record.

Sending file content as the request body

The bodyFromFile step field sends binary file content directly as the HTTP request body instead of a JSON payload constructed from field mappings. Use this when an external API expects the raw file content — for example, uploading a derived file to a third-party system.

{
  "stepType": "rest",
  "method": "PUT",
  "path": "/models/${file.metadataAttributes.modelId}/${derivedfile.name}",
  "bodyFromFile": {
    "contentType": "application/octet-stream"
  }
}

When bodyFromFile is present, SDMA reads the file content from the asset’s content-addressable storage using the file hash from the resource metadata. SDMA ignores the body and fieldMappings fields for that step.

Request body templates

The body step field provides a JSON body template with ${variable} references that SDMA resolves at execution time. Use this when the request body structure differs from what field mappings produce. For example, use body when the external API expects a specific JSON shape with nested objects or when you need to include values from $temp.* variables set by previous steps.

{
  "method": "POST",
  "path": "/v1/jobs",
  "body": {
    "imageUrl": "${file.contentUrl}",
    "assetId": "${asset.assetId}",
    "options": {
      "quality": "high"
    }
  }
}

SDMA scans each string value in the body for ${variable} references and resolves them against resource metadata and $temp.* variables. Non-string values (numbers, booleans, nested objects without variables) pass through unchanged.

SIGv4 signing for AWS service endpoints

When the security config type is AssumeRole, SDMA signs all HTTP requests with AWS Signature Version 4 (SIGv4) using the assumed role’s credentials. This allows REST connectors to call AWS service endpoints directly — for example, Amazon SageMaker inference endpoints, AWS Lambda function URLs, or Amazon Bedrock APIs.

SDMA determines the AWS service name for signing from the endpoint hostname:

{
  "restConfig": {
    "apiBase": "https://runtime.sagemaker.us-west-2.amazonaws.com",
    "securityConfig": {
      "type": "AssumeRole",
      "assumeRoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/SpatialDataManagementContentPublisher-SageMaker"
    }
  }
}

The assumed role must have permissions to invoke the target AWS service endpoint.

Session initialization

Some REST APIs require a session handshake before accepting requests. The restConfig.initialize block configures this. When present, SDMA sends a POST request to the specified endpoint before the first step executes and captures a session token from the response to include in all subsequent requests.

"restConfig": {
  "apiBase": "https://api.example.com",
  "initialize": {
    "path": "/session",
    "body": { "capabilities": {} },
    "sessionHeader": "X-Session-Id",
    "sessionField": "result.sessionId"
  },
  "securityConfig": { "..." }
}

Session initialization runs once per connector invocation. If initialization fails, the connector invocation fails.

Sampling

The restConfig.sampling block enables SDMA to respond to text-generation callbacks from external APIs that support this pattern. When configured, SDMA invokes a configured provider to generate a response and returns it to the external API before continuing with the connector step.

"restConfig": {
  "sampling": {
    "modelId": "abcd-20240307-v1:0",
    "securityConfig": {
      "type": "AssumeRole",
      "assumeRoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/SpatialDataManagementContentPublisher-Model"
    }
  }
}

Sampling requires session initialization (restConfig.initialize).

Safety and limits

The REST API client enforces the following safety measures: