registry: add reference

[craig-osterhout]

Description

Re-add registry reference from point in time of deletion at #18390, not upstream.

https://deploy-preview-22497--docsdocker.netlify.app/reference/api/registry/
https://deploy-preview-22497--docsdocker.netlify.app/reference/api/registry/token/

Related issues or tickets

ENGDOCS-2577

Reviews

• Technical review
• Editorial review
• Product review

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	8923720
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/682774d140f85c00083486a7
😎 Deploy Preview	https://deploy-preview-22497--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sarahsanders-docker]

before I do a more thorough review, I left a comment about why we are not using an OpenAPI spec to generate the documentation here

[sarahsanders-docker]

should we have a response?

ex:

{
  "schemaVersion": 2,
  "config": { "digest": "sha256:..." },
  "layers": [
    { "digest": "sha256:..." },
    ...
  ]
}

[sarahsanders-docker]

should this step be done first technically? same with the existing image one above? it might make more sense to check for existing ones beforehand

a logical order here might be:

1. Check for existing layers (HEAD call and response)
2. Start layer upload (POST call and response)
3. Upload blob (PUT/PATCH calls and response)
4. Complete upload (PUT call and response)
5. Cancel upload (DELETE call and response)

[sarahsanders-docker]

I left a bunch of inline comments, but overall:

• For every endpoint, ideally we would have: Request syntax (covered this well) and a valid response example (we are missing these)
• Some of the steps feel like they are out of order. Maybe this is my misunderstanding of how to use the Registry API, but I left some comments about checking if layers/images exist coming before the rest of the steps.
• Lots of gerunds in headings make it hard to skim/find action oriented phrases, I would suggest changing the headings to remove gerunds so I can skim the content and look for actions I want to execute
• Lots of headings don't appear on the right TOC which makes it hard to skim and find what I am looking for. Ideally I would see the entire API in the TOC so I can jump to the endpoint I want

A good example format for endpoint patterns might be something like (this keeps it easy to skim and get all the info I need per endpoint):

Get image manifest

GET /v2//manifests/

Required headers:

• Accept: example
• Authorization: Bearer

Success response:

example of request response `200 OK` w/ Content-type

Possible errors:

• 401
• 404

Happy to help restructure this if you want me to overhaul the endpoint sections for you to commit changes @craig-osterhout