Issue #2665
closedAPI documentation doesn't explain how to manage tags
Description
Let's say I've created and populated a docker repository, and that I'd now like to create a new tag, or update an existing tag. How do I do that? If using pulp-admin
, it's doable. I can look at the recipes on GitHub. But what if I want to do that via the API? There's no guidance on how to work with the API. In order to work with the API endpoints exposed by the pulp_docker plugin, I find myself running pulp-admin -vvv ...
. That's no fun. :(
To take a specific example, let's say that I have a repository containing a tag with the name "latest." How do I update this tag? Intuitively, I'd expect that I can make a POST or PUT request to this tag's _href. In reality, tags don't have an _href, or at least none that's advertised by the API. Here's an example of information about a tag from a search:
[{'_id': {'$oid': '58d40d036b45ba954e332fe3'},
'created': '2017-03-23T17:59:31Z',
'metadata': {'_content_type_id': 'docker_tag',
'_id': '6cf8e32b-5ae9-476f-9e1c-450676a3b904',
'_last_updated': 1490291971,
'_ns': 'units_docker_tag',
'manifest_digest': 'sha256:32f093055929dbc23dec4d03e09dfe971f5973a9ca5cf059cbfb644c206aa83f',
'name': 'latest',
'pulp_user_metadata': {},
'repo_id': 'db333e84-52a7-49a3-81e8-cf84435b6824',
'schema_version': 2},
'repo_id': 'db333e84-52a7-49a3-81e8-cf84435b6824',
'unit_id': '6cf8e32b-5ae9-476f-9e1c-450676a3b904',
'unit_type_id': 'docker_tag',
'updated': '2017-03-23T17:59:31Z'}]
There's no _href. Instead, a request is made to {repository_href}/actions/import_upload/
. Fair enough. It's not what I expected, but it makes some sense.
Now, what's included in the body of the POST request? Intuitively, I would expect that I could send something like this:
{
'metadata': {'manifest_digest': 'sha256:some-new-value'},
'unit_id': '6cf8e32b-5ae9-476f-9e1c-450676a3b904',
}
What I've done is named the unit that I want to update (because that information isn't embedded in the path I'm POSTing to) and twiddled some of the attributes as they were in response to my GET request, earlier. But that doesn't work. In reality, the body of the request should look like this:
{'unit_key': {'name': 'latest',
'repo_id': '1f399fa7-7109-45be-bbae-15baa92c369a'},
'unit_metadata': {'digest': 'sha256:d71ce73158269ca5688e129fd8a6dbc47e449b0608e0ec1603a0408dff575a5e',
'name': 'latest'},
'unit_type_id': 'docker_tag'}
Why do I need to insert 'name': 'latest'
into this request twice? I don't know. Again, the reason I know how to make this request is that I've observed the output of pulp-admin -vvv ...
.
Can we improve this situation? It's not fun to write tests for a plugin that only has pulp-admin documentation. It's also hard to fix the tests that have broken in 2.13 (due to an backwards-incompatible change in manifest paths - is that OK?) without knowing this stuff.