Skip to content

Writing to the Specification API

This page covers the write operations of the Specification API only. They are in the preview: check each operation's stage before you build on it.

Create: one call, all or nothing

A specification is created in one call, with its own chapters inside:

POST https://apis.traceone.com/spec/v2/food/specifications
POST https://apis.traceone.com/spec/v2/packaging/specifications
  • Everything the call creates exists after it, or nothing does. A refused value rejects the whole call with 422.
  • Shared objects are referenced by ID, not sent inline: library chapters, materials, packaging systems, requirements. Create them first, at their own address under /library/, then reference them.
  • A new specification is private to your company until you share it (POST .../share).

Import order

Create the leaves first:

  1. Materials and packaging components
  2. Library chapters and packaging systems
  3. Specifications that reference them
  4. Share

Update: one chapter at a time

There is no call that updates a whole specification. Each chapter has its own PUT:

PUT https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/labelling-chapter
  • Send the chapter's writable content. The description of each operation says what a missing section means.
  • A library chapter is updated at its own address (/library/...), not through a specification. The change is seen by every specification linked to it.
  • Attaching or replacing a library chapter on a specification is an action: POST .../link.

Concurrency: ETag and If-Match

Two writers in your company can change the same specification at the same time. To avoid overwriting someone else's change:

  1. Read the chapter with its GET. Keep the ETag response header.
  2. Send it back in If-Match with your PUT.
  3. If the specification changed since you read it, the answer is 412 Precondition Failed. Read the chapter again, apply your change to the new content, and retry.
GET https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/labelling-chapter
→ 200 OK
  ETag: "a1b2c3"

PUT https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/labelling-chapter
If-Match: "a1b2c3"
→ 204 No Content   (or 412 if it changed)

After a successful PUT, read the chapter again to get its new ETag.

If-Match is optional. Without it, your PUT replaces the content whatever changed since you read it.

Actions

Business steps are action calls, not field updates: POST .../share, POST .../link.

Running an action again changes nothing and answers 204. A retried action is always safe.

Retrying

CallOn a timeout or 5xx
PUT on a chapterRetry: it sends the same content again
Action (share, link)Retry
Create (POST .../specifications, POST /library/...)Do not retry blindly: a lost answer may hide a successful create. Check whether the resource exists first

Refusals

A refused write answers 422. Read the error code:

CodeMeaningWhat to do
UNPROCESSABLE_CONTENTA value is refused. The error names the fieldFix the value
INVALID_RESOURCE_STATEThe resource's state does not allow the write, for example the chapter is locked while the specification is in signatureWait or fix the resource; the request itself is fine
NAME_ALREADY_USEDThe name of a library object is already used in your companyPick another name

The Specification API never answers 409. See Errors for the error body.

Next steps

Coding practices

Errors