[Pulp-dev] Unified interface for plugin actions

[Austin Macdonald]

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 at ./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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190228/1831a341/attachment.htm>