[Pulp-dev] Unified interface for plugin actions

[Justin Sherrill]

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 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.