As a plugin writer, I have docs to define endpoints for multiple namespaced content types
Any plugin objects can run into this problem, so the documentation should be general to remotes, publishers, exporters, and content types.
Explain that namespacing is optional but encouraged, the long term problems that it can avoid, and how it is done in the viewset.
This change will be a part of a larger plugin-writer change, so please open this PR against that feature branch:
These docs should be put here:
these docs https://github.com/asmacdo/plugin_template/blob/add-plugin-writer-docs/docs/plugin-writer/subclassing/namespacing.rst
Working on the Ansible plugin, we have multiple content types (roles, role versions, and more in the future). For role, I was thinking about defining my content viewset to be 'role' which pulpcore automatically sets up as "/api/v3/content/role/". See:
That got me thinking: what if another plugin has a role type?
Apparently if I have two viewsets that define type 'role', the application just selects one of the two. I can't make out which it prefers though.
By convention (meaning, in the plugin docs), plugins are encouraged to namespace their "Detail" endpoints by plugin name.
This is done in the viewset:
class AnsibleRoleViewSet(ContentViewSet): # the endpoint becomes v3/content/ansible/roles endpoint_name = 'ansible/roles' queryset = AnsibleRole.objects.all() model = AnsibleRole serializer_class = AnsibleRoleSerializer
For some plugins, this is awkward because they only have one type, like the file plugin. Following this convention, the endpoint will be v3/content/file/files/. If the file plugin chooses, they can keep v3/content/file/, but if they do this, they should be aware that adding other content types later will either create inconsistency or will be backwards incompatible. v3/content/file/newfile/.
#4 Updated by email@example.com over 2 years ago
I think the way to do this would be an extension of the master/detail concept we already have, where Content ViewSets are registered under the url:
This would be awkward for plugins with only 1 type:
I think I prefer establishing the convention:
If the type is different than the plugin name, the plugin name should be a part of the type in the url.
#7 Updated by daviddavis over 2 years ago
I think plugins should either use
/content/<plugin>/<type>/ regardless of how many content types they have.
I am a bit worried about the idea of allowing plugins with one content type use a different convention for a few reasons:
1. It's inconsistent with plugins that will have multiple content types
2. A plugin could start out with a single content type (
/content/rpm/) and then add more later (e.g. erratum, srpm, etc). At this point though, they've painted themselves into a corner and are forced to update existing routes.
3. It's unclear to me whether file in
v3/content/file refers to the content type or the name of the plugin. If it's the former, then what if I have another plugin with a content type of 'file'?
#10 Updated by firstname.lastname@example.org over 2 years ago
- Description updated (diff)
This was discussed on the list: https://www.redhat.com/archives/pulp-dev/2018-April/msg00050.html
I've updated the issue to match the consensus.
Please register to edit this issue