[cryptalith]

What

• The generated Member API spec. openapi/orcid-member-api.json is now the Member API description that
  ORCID-Source generates (COMMS-5397: COMMS-5397 (a) OpenAPI generator wiring for API v3.0 ORCID/ORCID-Source#7758, #7759, #7760). It is presented for the docs:
  sandbox servers, bearerAuth first for try-it, JSON only.
  • It covers all 116 operations; before, it covered the 6 employment ones.
  • It carries 94 recorded examples.
• The Public API spec, new. openapi/orcid-public-api.json covers the Public API's 56 operations.
• Employment examples, now recorded. They keep this POC's keys and pairings (minimal, missing-city,
  put-code-mismatch, ...), but each is recorded rather than written by hand. Where the hand-written ones
  disagreed with the API, the recorded ones show what the API does:
  • an unknown iD with a user's token is 401 (9017); 404 needs a 2-legged token;
  • a read is refused for a missing scope (403, 9038) only when another client added the item and it isn't
    public; a client can always read what it added.
• New guides: Read a record, Add and update works, Search the registry. Each says which host it uses; Read a
  record has a "When a read fails" table of the errors the suite produced.
• Add an employment fixes:
  • The "prevents duplicates" example used other-id, which the API stores as other_id, so a second one never
    matches the first. It now uses grant_number, which answers 409 (9021) the second time.
  • The error table is corrected: no token, or a public client's token, is 403 forbidden; malformed JSON is a
    plain-text 400, not 9047; 401 9017 also covers an iD that doesn't exist; the impossible 404 row is gone.
  • The url rule now says the API also takes a bare string.
• Quickstart: it says what the docs cover now and links the guides.
• Also on this branch: the unmerged lmendoa/update-delete (808dce0) and a merge of the latest main.

Every code block is checked

The contract suite checks every code block on these pages against a disposable Registry. cURL, Python and
JavaScript blocks are run, with the sandbox hosts and the placeholders (0000-0002-1825-0097, <ACCESS_TOKEN>,
1234567) swapped for the test stack's values; a run block can reach only the stack. A JSON payload block is
sent to its operation and must get the documented answer; a response block is validated against the spec:

• 64 blocks pass across both POCs (run, payload or response).
• Blocks skipped for a stated reason: the authorize URL, the authorization-code exchange and its token
  response, a displayed 201, and the placeholder text on ReadMe's welcome page.
• Changes fail the check: a block that changes fails until its entry in the suite's docs/manifest.yaml is
  reviewed again.

The reference examples are recorded the same way: each is a request and response the suite sent to a running
Registry. They are normalised to the docs' persona, placeholders and sandbox hosts.

Before merging

Create a spec named Orcid-Public-POC in GitBook from openapi/orcid-public-api.json. The new "Public API
reference" block in api-reference/SUMMARY.md points at it and shows nothing until it exists.

After merging

1. Refresh Orcid-POC in GitBook. If it was imported from a URL, use "Check for updates". Otherwise run
   npx -y @gitbook/cli@latest openapi publish --spec Orcid-POC --organization <org-id> openapi/orcid-member-api.json
   with your GITBOOK_TOKEN. Do the same for Orcid-Public-POC when the public spec changes.

Not changed

product-docs/guides/write-update-and-delete-works.md (Mari's v2.1 XML guide). The new "Add and update works"
page has tested v3.0 examples it could point to.