Skip to main content

REST API styles

API Studio

Each style is a template in New API. A template fills in the paths, methods, status codes, headers and schemas for that style. Every style runs on a deployed API through the same URL, keys and policies as any other endpoint.

Resource CRUD​

  • GET /items, POST /items, and GET, PUT, PATCH and DELETE on /items/{id}.
  • A body that does not match the schema answers 400 and never runs the flow.
  • A method the path does not define answers 405 with an Allow header.

Query and filter​

  • GET /items with filter and sort query parameters, and GET /items/{id}.
  • The flow receives the parameters in query.
  • A sort value outside the defined list answers 400.

Cursor pagination​

  • GET /items with cursor and limit. The flow returns nextCursor for the next page.
  • A limit above the defined maximum answers 400.

Search with a body​

  • QUERY /items sends search criteria in the body of a safe, repeatable request.
  • POST /items:search is the same search for clients that cannot send QUERY.
  • The body is validated like a POST body. QUERY is listed in Allow and in CORS responses.

Optimistic concurrency​

  • A GET answer carries an ETag. A request with a matching If-None-Match answers 304.
  • PUT, PATCH and DELETE send the last ETag in If-Match.
  • If-Match: * matches any current version, and If-Match accepts a list of tags.
  • A stale If-Match answers 412.
  • A missing If-Match answers 428 on endpoints that declare a 428 response. The Design preview answers 428 the same way.

Bulk and batch​

  • POST /items:batch takes a list of items and answers 207 with one result per item.
  • Each result has its index and status. A failed item carries a problem details object for that item only.

Long-running operation​

  • The endpoint answers 202 with a Location header at once.
  • Poll Location for the status, and the result once the flow ends.
  • A failed operation reports failed without the internal error text.

Actions on a resource​

  • A custom action is a path such as POST /items/{id}:approve.
  • The action path is matched before the plain /items/{id} path.
  • Another method on the action path answers 405. The Allow header lists the action methods.

File upload and download​

  • An upload is a multipart/form-data request. The flow receives each form field and each file with its name, file name, content type, size and content.
  • An upload past the maximum upload size answers 413.
  • A download answers the file bytes with a Content-Disposition header. File names outside ASCII are sent in filename*.
  • A download past the maximum download size answers 502.

Streaming​

  • GET /items:watch answers Server-Sent Events (text/event-stream). Each flow row is one event.
  • GET /items:export answers JSON Lines (application/jsonl), one JSON object per line.
  • An idle stream receives a keep-alive comment. A stream that stays idle past the stream idle timeout ends.
  • An error after the first event ends the stream with an error event in problem details format.

Callbacks and webhooks​

  • An operation lists its callbacks in the definition. The callback URL is read from the request, as {$request.body#/callbackUrl}.
  • When a long-running operation ends, each callback receives a POST with the operation status.
  • Every callback carries an X-DataLug-Signature header and an X-DataLug-Event header.
  • Callback URLs must use https. Private and internal addresses are refused.
  • Webhooks are listed at the top level of the definition and appear in the reference docs.

Private Agents​

  • A long-running endpoint deployed to an environment on a Private Agent in pull mode runs on that agent. The agent picks the call up as work, with the pinned flow version.
  • The operation status follows the agent's run: running, succeeded or failed.
  • When the run succeeds, the operation returns the API Response: its status, headers and body.
  • A request larger than 24 KiB is refused before it reaches the agent.
  • The API Response is limited to 1 MiB.
  • An API Response past the limit is not returned. The operation result is a 502 problem of type urn:datalug:problem:api:agent-result-too-large.
  • A synchronous endpoint on a pull mode Private Agent answers 409.