[docker-hub-api] add list namespace repositories endpoint #22934
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| ### New | ||
| | ||
| - Add [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories) endpoints for a given `namespace`. | ||
| - Deprecate undocumented endpoint `GET /v2/repositories/{namespace}` replaced by [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories). |
There was a problem hiding this comment.
Not sure what we did in the past, but perhaps for visibility (although there’s only 2 things in the bullets), we could use ### New for the new endpoint, and a ### Deprecations (or similar) for what’s deprecated. That could also add a link to the “deprecated” page (refer to “deprecated” for a list of deprecated API endpoints / API features)
There was a problem hiding this comment.
Probably also want to add a mention in deprecated; not sure if we have a good format for that already, but there’s some existing things that were deprecated; https://github.com/docker/docs/blob/main/content/reference/api/hub/deprecated.md
We should probably start thinking of some more formalized deprecation document (what’s our policy, how announced, etc), although in most cases actually removing endpoints / features from the API may be more complicated, or at least, not without a major version bump of the API and ultimately fully dropping support for prior major versions; https://docs.docker.com/engine/deprecated/
There was a problem hiding this comment.
I have reformat and reorganize a bit "Docker Hub API" and "DVP Data API" to have the same structure : Changelog, Deprecated and OpenAPI.
The message in deprecated is pretty generic and strongly inspired by https://docs.docker.com/engine/deprecated/ with "date" instead of "release" and "endpoint" instead of "feature".
content/reference/api/dvp/latest.md Outdated
| linkTitle: DVP Data API | ||
| title: Docker Verified Publisher API reference | ||
| weight: 4 | ||
| title: OpenAPI |
There was a problem hiding this comment.
Looks like the title went missing here as well; can you add those back (title and a short linkTitle for the navigation)
As this page moved, we'd also want to add aliases here;
| title: OpenAPI | |
| title: Docker Verified Publisher API reference | |
| linkTitle: DVP Data API | |
| aliases: | |
| - /reference/api/hub/dvp/ |
Instead of making latest the canonical URL, we could consider keeping it as index (_index.md), adding /reference/api/hub/dvp/latest/ as alias. We do this for the Engine API, where https://docs.docker.com/reference/api/engine/latest/ (for convenience) links to the versioned URL for the latest API version; https://docs.docker.com/reference/api/engine/version/v1.50/
There was a problem hiding this comment.
Now http://localhost:1313/reference/api/hub/dvp/ -> http://localhost:1313/reference/api/dvp/latest/` OK
There was a problem hiding this comment.
I don't know the app behind these dvp endpoints so I would not know what to put as version.
Can this be done later when the team responsible for DVP will update there openapi.yaml ?
And for docker hub api, the endpoints are a collection from multiple services so I don't know what should I put as a version too :/
There was a problem hiding this comment.
Can't comment inline because there's no diff in the file; not sure if people reference this file directly (if that's the case, we may need to add a redirect through other means).
There was a problem hiding this comment.
Now http://localhost:1313/reference/api/hub/dvp.yaml -> http://localhost:1313/reference/api/dvp/latest.yaml OK
There was a problem hiding this comment.
changes LGTM, but could use some more eyes - perhaps @sarahsanders-docker wants to give it a look?
Some notes;
- Still a bit on the fence on
OpenAPIin the navigation - perhaps "latest" isn't too bad to use, or "reference"? - I tried if I could somehow make the
/reference/api/dvp/URL work; it's currently a 404 (probably because the_index.mdis marked as "don't render"), but I was hoping we could somehow make it show something sensible (e.g., the first link in the list ("changelog"?) - ☝️ alternatively, we should have an actual index page to describe what API this is
| OpenAPI is confusing and not intuitive for navigation. It should say "Latest" to align with the drop down nav in Engine API. Also, I think the latest version of the API should come first, followed by Changelog, followed by Deprecated. As for the |
| As @sarahsanders-docker and @thaJeztah suggested :
For the |
Description
GET /v2/namespaces/{namespace}/repositoriesAfter the comments from @thaJeztah
Related issues or tickets
Reviews