Documentation

Appearance

Product Application API #

The Product Application API gives a customer system access to the published records and Operations of one Product Instance. It is separate from the organisation-scoped Gateway API and from the OEM authoring interfaces used to edit an application.

Follow the generated contract for the Product Instance for its origin, paths, published models, fields, and Operations. Do not copy routes from the Dataplicity browser application.

Authenticate an instance client #

Create an API client for the target Product Instance under Access. A client secret belongs to that instance and is accepted as either an ApiKey value in the Authorization header or in X-API-Key.

Store the plaintext secret in server-side secret storage. It is returned when the client is created and stored by Dataplicity as a hash. Revoked clients no longer authenticate.

Clients can be scoped to all records, a named model, or exposed Operations. The implemented scope vocabulary includes:

  • records:read and records:write
  • model:<key>:read and model:<key>:write
  • operations:invoke and operation:<key>
  • *

The API applies the client's configured per-minute rate limit after checking scope. A rate-limit failure returns 429.

Address the published contract #

Every request identifies a Product Instance. The client credential and the instance identifier must resolve to the same instance; a client cannot become a cross-customer credential.

Record requests also identify a published model by its model key. Record responses carry both model_key and the immutable model_stable_id, plus the published schema_version. Use the generated contract's field keys when constructing requests. Stable IDs in responses support schema-aware tooling, but do not replace the published field contract.

Read response envelopes #

A record response includes:

  • id, model_key, model_stable_id, and schema_version
  • record_version for optimistic concurrency
  • data_by_key for published customer-visible field keys
  • data keyed by field stable ID
  • fields with the visible field definitions
  • archived_at, created_at, and updated_at

Query responses use results, next_cursor, page_size, and model. total_count appears only when requested. Aggregate responses use model and metrics, with grouping metadata when grouping or time bucketing is requested.

Handle errors #

Validation errors use a JSON detail value and return 400. Authentication failures return 401; an instance mismatch or insufficient scope returns 403. A missing active record returns 404.

A stale record_version returns 409 with detail: "Conflict" and the current record_version. Reusing an idempotency key for a different mutation also returns 409. Treat 429 as rate limiting and apply a bounded retry policy.

Do not parse human-readable detail text to drive business logic. Validate requests against the generated contract and handle status classes explicitly.

Make mutations idempotent #

Send Idempotency-Key on record creates, updates, and archives. The key is scoped to the API client. Repeating the same method, target, and body returns the stored response; changing the request while reusing the key is a conflict.

Operation invocation also accepts an idempotency key. Keep one stable key for one business intent and retain it through network retries.

Idempotency prevents a repeated API request from creating another cloud-side intent. It does not make downstream physical, financial, or third-party side effects exactly once. Reconcile important outcomes against their authoritative system.