As a plugin writer, I have documentation on how to create live api endpoints responsibly
Working on the Ansible plugin, I need to define a live api that can serve up Galaxy metadata. I'm imagining for roles for example, this might live at "/api/v3/roles/" but I have some concerns obviously. Namely, is my url going to conflict with other plugins or pulpcore? Also what docs do I look at to know how to add these urls?
Add a new page called 'Adding Views' as a top-level section of the Plugin Writer's Guide . This documentation must:
1. Document how to define a url endpoint that Pulp core will serve
2. Document and advise plugin writers to namespace their Live API routes whenever possible to:
#6 Updated by bmbouter about 2 years ago
Yes we need a way to have a plugin provide a view at a URL like /mytoplevelview/ This comes from the live API MVP requirements since some content APIs have hard-coded expectations. This may make some plugins incompatible but that's because their live APIs fundamentally are. I can't give an example because the idea of colliding viewsets is still a theoretical problem.
I'm +1 on option 2. I think it would be good for core to document a recommended a convention whereby plugin views are namespaced by plugin name.
I do not think we need a way to enforce or guarantee that plugin views won't collide.
#13 Updated by bmbouter about 2 years ago
I like the story as it's written.
Which page in the docs is this going on? I couldn't find a section on "adding Live APIs". If not we should add one along w/ this ticket. Or maybe another docs piece of work is adding something like that?
Also another idea: since /api/v3/ is kind of popular maybe the Pulp prefix should be be /pulpapi/v3/ instead?
#15 Updated by daviddavis about 2 years ago
I'm imagining that the scope of this is much larger than just Live APIs so I think it would be best to either add this to the plugins/plugin-writer/basics.rst under an "API routes" section or maybe add a completely new page about how to define new routes/views in plugins.
#17 Updated by bmbouter about 2 years ago
- Subject changed from As a plugin writer, I have a way to create api endpoints and know they don't conflict with other plugins and pulpcore to As a plugin writer, I have documentation on how to create api endpoints responsibly
- Description updated (diff)
Rewriting to call out a bit more documentation needed with the ticket.
#29 Updated by email@example.com almost 2 years ago
My current plan is not to include live-api docs in the main plugin writer walkthrough, instead to include it in a reference section, which will be be linked to at the end of the walkthrough as "next steps" or "advanced".
Please open a PR to a feature branch for plugin-writer docs:
Note, please review whats already there. I'm not sure its correct to say that this is primarily a publishing thing.
Please register to edit this issue