To me this makes a lot of sense, allows for plugin flexibility, and is
more consistent across plugins.
I feel like this will make differences between plugins more
understandable by reading the api docs, rather than scanning the
README's of the respective plugin and trying to work out what is different.
Justin
On 2/28/19 1:42 PM, Austin Macdonald wrote:
Now that we have a handful of plugins that have somewhat different
workflows, surprising user-facing differences in the interface for
plugin-related actions are becoming apparent.
Example: Publish
File:
Create a publisher
v3/publishers/file/1/publish/ repository=$REPO
Ansible:
(no publisher)
v3/publications/ repository=$REPO
The difference is not huge, having a different endpoint does defy
expectations of a user who is familiar with one plugin, who then moves
to another plugin.
Plugins can also implement other endpoints, like RPM's one-shot
upload. The problem is that we have mixed idioms. Plugins are
encouraged to create task endpoints for objects (remote's sync,
publisher's publish), but they are also encouraged to create arbitrary
endpoints for any other actions. Users are not able to form reasonable
expectations for this part of the interface from plugin to plugin.
Proposal:
We could move all "actions" into a single area, namespaced by plugin
(by convention). This would allow the plugins the freedom to do
whatever they need to do while keeping the interface consistent and
predictable for users of multiple plugins. These "actions" could be
synchronous or asynchronous. Importantly, this would also create a
logical "group" of endpoints a user could look for in the REST API docs.
Examples:
v3/actions/file/publish/ publisher=$PUB repository=$REPO
v3/actions/ansible/publish/ repository=$REPO
v3/actions/rpm/upload/ file@./foo-4.1-1.noarch.rpm repository=$REPO
Will this push back the RC?
No. The changes to the plugin API will be small, and the changes to
each plugin would be moving sync and publish endpoints, leaving the
logic almost identical. I anticipate the most time consuming aspect of
this will be adjusting the documentation of each plugin-- but since
they will follow similar patterns, this shouldn't be too much work either.
To sum up:
We should move sync and publish endpoints to
/actions/<plugin>/<action_name>/ to be consistent with other
plugin-defined actions like one-shot upload. This will look very nice
in swagger docs, and should provide more consistent workflows for
users of multiple plugins.
_______________________________________________
Pulp-dev mailing list
Pulp-dev@redhat.com
https://www.redhat.com/mailman/listinfo/pulp-dev
