Documentation for API https://hub.docker.com/v2/repositories/${repository}

[miparnisari]

Hello, where can i find documentation for this endpoint? https://hub.docker.com/v2/repositories/${repository}

The reason I ask: there is one Github action that calls it to update a repository's description, and this piece:

https://github.com/peter-evans/dockerhub-description/blob/579f64ca0abced29dbbc44ab4c6a0b9e33ab3588/src/dockerhub-helper.ts#L39-L46

fails unless the access token has the read, write AND delete scope. And i don't understand why it needs delete.

[milosgajdos]

There is no public documentation for this API endpoint I'm afraid.

We're working on updating the Hub API documentation, but we don't have any timelines for when that work will be completed at the moment.

I wanted to point out one more thing, though, as a heads up. The API endpoint you're mentioning is rather confusing -- I suspect the confusion arises from the way the JS code uses it in the GH Action. It seems to concatenate namespace and repository and use it as a single API resource to be taken action on i.e. ns/repo -> repo.

The properly spelled-out API endpoint you're mentioning is as follows:

https://hub.docker.com/v2/repositories/${namespace}/${repository}

The reason why I'm mentioning this is, the API endpoints like the one above will become legacy endpoints because they're confusing (as manifested by the GH Action you mention) and will be replaced with the ones that make each API resource explicit i.e.

https://hub.docker.com/v2/namespaces/${namespace}/repositories/${repository}

Now, back to your original question, sorry about the interlude. The author of the GH Action is right in assuming the need for the delete permissions:

my guess is that read/write/delete is considered "admin" level permission, which is what they seem to require for modifying the description of a repository.

Only admins are allowed to make modifications to the repositories and at the moment they require delete permissions.

Now, we are currently actively working on revamping the permission models slightly, so in the [hopefully] near future there will not be any need for delete scopes on this and a few other API endpoints. Please bear with us 🙇‍♂️

[peter-evans]

@milosgajdos Thank you for the explanation.

Would this be right issue to follow progress on the new API? https://github.com/docker/roadmap/issues/20

[milosgajdos]

Yes, thats the correct issue to track the Hub API @peter-evans

[milosgajdos]

@miparnisari feel free to close this issue if you think it was answered :)

[miparnisari]

Thank you @milosgajdos!