REST endpoints

A REST connection is the most generic shape: an HTTP target DataMaker will POST to when you push a template, or GET from when a scenario fetches data. Use it for any service that doesn’t have a more specific connection type (databases, SAP OData).

Create a REST connection

Project → Connections → New → REST. Fill in:

Name — display name.
Base URL — e.g. https://api.acme.com/v1. All paths are resolved against this.
Auth: none, basic, bearer, api-key (header or query), or oauth2-client-credentials.
Default headers — JSON object. Common headers like Content-Type: application/json go here.

Click Verify. DataMaker makes a HEAD (or OPTIONS, then GET) against the base URL and reports the response.

Auth flows

Bearer

Authorization: Bearer ${secret_ref}

Static token stored as a secret. Rotate by editing the secret; the connection auto-picks up the new value.

API key (header or query)

For services that use X-API-Key: ... or ?api_key=.... Choose the location in the form.

OAuth2 client credentials

DataMaker handles the token exchange:

You provide token_url, client_id, client_secret.
We mint a token, cache it for the response’s expires_in, and refresh automatically.
Push and fetch operations transparently use the current token.

For OAuth2 authorization code (user-flow), use a Bearer token and refresh it yourself; we don’t run a redirect listener.

Push a template

When you push a template to a REST connection, DataMaker:

Resolves the target — either a fixed path on the connection (POST /customers) or a path you set in the push dialog.
For each row, makes one POST with the row as the JSON body.
Records status codes per row in the run log.

For batch endpoints (one POST with an array of objects), set Push mode → Batch and provide a wrapper key:

{ "items": [ { ... }, { ... } ] }

We’ll wrap the rows for you.

Fetch from a REST endpoint

Templates can declare a field as api_response to pull the value from a REST call:

{
  "name":    "country_name",
  "type":    "api_response",
  "options": {
    "connection_id": "conn_rest_geo",
    "path":          "/countries/{{country_code}}",
    "extract":       "$.name"
  }
}

extract is a JSONPath expression. The value at that path becomes the field value.

For full table fetches (e.g. “give me all customers from /customers?country=DE”), use a scenario — scenarios have proper pagination support.

Retries & timeouts

Default policy:

Timeout: 30s per request.
Retries: 3, with exponential backoff (1s, 2s, 4s).
Retry on: 429, 502, 503, 504, network errors.
No retry on: 4xx other than 429 (we don’t retry application errors).

Override in the connection form or per-push.

Custom request shape

If your endpoint expects something other than Content-Type: application/json with the row as the body, configure a request template:

{
  "method":  "POST",
  "path":    "/v1/customers",
  "headers": { "X-Tenant": "{{tenant_id}}" },
  "body": {
    "customer": {
      "name":     "{{first_name}} {{last_name}}",
      "email":    "{{email}}",
      "metadata": {{extra | json}}
    }
  }
}

{{...}} references the row’s fields. Filters: | json, | upper, | lower, | date('YYYY-MM-DD').