{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Writing to the Specification API"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"writing-to-the-specification-api","__idx":0},"children":["Writing to the Specification API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers the write operations of the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Specification API"]}," only. They are in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/api-versioning#stages"},"children":["preview"]},": check each operation's stage before you build on it."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-one-call-all-or-nothing","__idx":1},"children":["Create: one call, all or nothing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A specification is created in one call, with its own chapters inside:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST https://apis.traceone.com/spec/v2/food/specifications\nPOST https://apis.traceone.com/spec/v2/packaging/specifications\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Everything the call creates exists after it, or nothing does. A refused value rejects the whole call with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Shared objects are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["referenced by ID"]},", not sent inline: library chapters, materials, packaging systems, requirements. Create them first, at their own address under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/library/"]},", then reference them."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A new specification is private to your company until you share it (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../share"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"import-order","__idx":2},"children":["Import order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the leaves first:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Materials and packaging components"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Library chapters and packaging systems"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Specifications that reference them"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Share"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-one-chapter-at-a-time","__idx":3},"children":["Update: one chapter at a time"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no call that updates a whole specification. Each chapter has its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/labelling-chapter\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send the chapter's writable content. The description of each operation says what a missing section means."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A library chapter is updated at its own address (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/library/..."]},"), not through a specification. The change is seen by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every"]}," specification linked to it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Attaching or replacing a library chapter on a specification is an action: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../link"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"concurrency-etag-and-if-match","__idx":4},"children":["Concurrency: ETag and If-Match"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two writers in your company can change the same specification at the same time. To avoid overwriting someone else's change:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the chapter with its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},". Keep the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETag"]}," response header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send it back in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["If-Match"]}," with your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the specification changed since you read it, the answer is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["412 Precondition Failed"]},". Read the chapter again, apply your change to the new content, and retry."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/labelling-chapter\n→ 200 OK\n  ETag: \"a1b2c3\"\n\nPUT https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/labelling-chapter\nIf-Match: \"a1b2c3\"\n→ 204 No Content   (or 412 if it changed)\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After a successful ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]},", read the chapter again to get its new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETag"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["If-Match"]}," is optional. Without it, your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," replaces the content whatever changed since you read it."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"actions","__idx":5},"children":["Actions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Business steps are action calls, not field updates: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../share"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../link"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Running an action again changes nothing and answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]},". A retried action is always safe."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrying","__idx":6},"children":["Retrying"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Call"},"children":["Call"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"On a timeout or 5xx"},"children":["On a timeout or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," on a chapter"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry: it sends the same content again"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Action (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["share"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST .../specifications"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /library/..."]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not retry blindly"]},": a lost answer may hide a successful create. Check whether the resource exists first"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"refusals","__idx":7},"children":["Refusals"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A refused write answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},". Read the error code:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNPROCESSABLE_CONTENT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A value is refused. The error names the field"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_RESOURCE_STATE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The resource's state does not allow the write, for example the chapter is locked while the specification is in signature"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait or fix the resource; the request itself is fine"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NAME_ALREADY_USED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The name of a library object is already used in your company"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pick another name"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Specification API never answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/errors"},"children":["Errors"]}," for the error body."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":8},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/errors"},"children":["Errors"]}," — status codes and the error body"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/catalog/spec/v2-preview/specifications/openapispecification"},"children":["Specification preview"]}," — every write operation with its stage"]}]}]},"headings":[{"value":"Writing to the Specification API","id":"writing-to-the-specification-api","depth":1},{"value":"Create: one call, all or nothing","id":"create-one-call-all-or-nothing","depth":2},{"value":"Import order","id":"import-order","depth":3},{"value":"Update: one chapter at a time","id":"update-one-chapter-at-a-time","depth":2},{"value":"Concurrency: ETag and If-Match","id":"concurrency-etag-and-if-match","depth":2},{"value":"Actions","id":"actions","depth":2},{"value":"Retrying","id":"retrying","depth":2},{"value":"Refusals","id":"refusals","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Writing to the Specification API","description":"How to create specifications, update chapters safely with If-Match, retry, and read refusals in the Specification API.","seo":{"title":"Writing to the Specification API"}},"lastModified":"2026-10-27T11:55:12.929Z","pagePropGetterError":{"message":"","name":""}},"slug":"/getting-started/writing-to-specification","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}