+1 to what Justin said. I think it's a huge benefit to have the differences between plugins show up in the api docs together.
Dana Walker Associate Software Engineer Red Hat <https://www.redhat.com> <https://red.ht/sig> On Fri, Mar 1, 2019 at 2:00 PM Justin Sherrill <jsher...@redhat.com> wrote: > 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 >
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
