Project

Profile

Help

Story #3472

closed

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

Added by daviddavis over 6 years ago. Updated almost 5 years ago.

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

100%

Estimated time:
Platform Release:
Groomed:
Yes
Sprint Candidate:
Yes
Tags:
Documentation, Plugin Template
Sprint:
Sprint 42
Quarter:

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'MODIFIEDamacdona@redhat.comActions
Related to File Support - Task #3601: Move /content/file/ to /content/file/files/CLOSED - CURRENTRELEASEdaviddavis

Actions

Also available in: Atom PDF