Project

Profile

Help

Story #3472

As a plugin writer, I have docs to define endpoints for multiple namespaced content types

Added by daviddavis over 1 year ago. Updated 6 months ago.

Status:
MODIFIED
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

100%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
Documentation, Plugin Template
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 42

Description

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:
https://github.com/asmacdo/plugin_template/tree/add-plugin-writer-docs

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

Background

Problem:
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:

https://github.com/pulp/pulp_file/blob/master/pulp_file/app/viewsets.py#L32

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.

Solution:
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/.


Related issues

Related to Python Support - Issue #3572: Move 'content/python' to 'content/python/packages' MODIFIED Actions
Related to File Support - Task #3601: Move /content/file/ to /content/file/files/ MODIFIED Actions

History

#1 Updated by daviddavis over 1 year ago

  • Tags Pulp 3 MVP added

#2 Updated by daviddavis over 1 year ago

  • Description updated (diff)

#3 Updated by daviddavis over 1 year ago

  • Description updated (diff)

#4 Updated by amacdona@redhat.com over 1 year 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:

v3/content/<plugin>/<type>/

This would be awkward for plugins with only 1 type:

v3/content/file/file/
v3/content/python/python/

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.
/v3/content/python/
v3/content/ansible-role/

#5 Updated by dalley over 1 year ago

  • Tracker changed from Issue to Story
  • % Done set to 0

#6 Updated by daviddavis over 1 year ago

  • Subject changed from Plugin writers can define types which conflict with other plugins to As a plugin writer, I can define types which does not conflict with other plugins

#7 Updated by daviddavis over 1 year ago

I think plugins should either use /content/<plugin>-<type>/ or /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'?

#8 Updated by bmbouter over 1 year ago

+1 to using /content/<plugin>/<type>/.

#9 Updated by daviddavis over 1 year ago

  • Subject changed from As a plugin writer, I can define types which does not conflict with other plugins to As a plugin writer, I can define endpoints for multiple content types and be assured my endpoints don't conflict with other plugins

#10 Updated by amacdona@redhat.com over 1 year 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.

#11 Updated by daviddavis over 1 year ago

  • Description updated (diff)

#12 Updated by bmbouter over 1 year ago

  • Groomed changed from No to Yes
  • Tags Documentation added

This story looks fully groomed with agreement from several other core devs. I also tagged it as a docs story.

#13 Updated by amacdona@redhat.com over 1 year ago

  • Sprint Candidate changed from No to Yes

#14 Updated by amacdona@redhat.com over 1 year ago

  • Sprint set to Sprint 35

#15 Updated by amacdona@redhat.com over 1 year ago

  • Subject changed from As a plugin writer, I can define endpoints for multiple content types and be assured my endpoints don't conflict with other plugins to As a plugin writer, I have docs to define endpoints for multiple namespaced content types

#16 Updated by daviddavis over 1 year ago

  • Related to Issue #3572: Move 'content/python' to 'content/python/packages' added

#17 Updated by dkliban@redhat.com over 1 year ago

  • Sprint/Milestone set to 3.0

#18 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 35 to Sprint 36

#19 Updated by daviddavis over 1 year ago

  • Related to Task #3601: Move /content/file/ to /content/file/files/ added

#20 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 36 to Sprint 37

#21 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 37 to Sprint 38

#22 Updated by amacdona@redhat.com over 1 year ago

  • Project changed from Pulp to 27
  • Sprint/Milestone deleted (3.0)

#23 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 38 to Sprint 39

#24 Updated by amacdona@redhat.com over 1 year ago

  • Description updated (diff)

#25 Updated by daviddavis over 1 year ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to daviddavis

#26 Updated by daviddavis over 1 year ago

  • Status changed from ASSIGNED to POST

#27 Updated by dkliban@redhat.com over 1 year ago

  • Sprint changed from Sprint 39 to Sprint 40

#28 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 40 to Sprint 41

#29 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 41 to Sprint 42

#30 Updated by dalley about 1 year ago

  • Status changed from POST to MODIFIED

#31 Updated by werwty about 1 year ago

  • % Done changed from 0 to 100

Applied in changeset commit:d73ec31f75db6dfdebab8742982ea350cb0475a8.

#32 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3, Pulp 3 MVP)

#33 Updated by bmbouter 6 months ago

  • Tags Plugin Template added

#34 Updated by bmbouter 6 months ago

  • Project changed from 27 to Pulp

The plugin template Redmine project is being consolidated into the Pulp Redmine project so all issues are being moved over.

#35 Updated by bmbouter 6 months ago

  • Sprint/Milestone set to 3.0

Please register to edit this issue

Also available in: Atom PDF