Project

Profile

Help

Story #3473

As a plugin writer, I have documentation on how to create live api endpoints responsibly

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

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

0%

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

Description

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:

v3/plugins/<plugin_type>/something/

Related issues

Related to Pulp - Story #3560: As a plugin writer, I can write views (at arbirary endpoints) which are discovered and registered with pulpcore. MODIFIED Actions

History

#1 Updated by daviddavis over 1 year ago

  • Tags Pulp 3, Pulp 3 MVP added

#2 Updated by daviddavis over 1 year ago

  • Subject changed from No way to create api endpoints and be sure that they don't conflict with other plugins to No way to create api endpoints and be sure that they don't conflict with other plugins and pulpcore

#3 Updated by daviddavis over 1 year ago

  • Description updated (diff)

#4 Updated by dalley over 1 year ago

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

#5 Updated by daviddavis over 1 year ago

  • Subject changed from No way to create api endpoints and be sure that they don't conflict with other plugins and pulpcore to As a plugin writer, I have a way to create api endpoints and know they don't conflict with other plugins and pulpcore

#6 Updated by bmbouter over 1 year 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.

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

I think it would be nice to prevent collisions, but for the time being Option 2 seems good.

In addition to "encouraging namespacing" we could encourage a specific convention.

#8 Updated by daviddavis over 1 year ago

@asmacdo, +1. What about for a convention we use /api/v3/plugin/<plugin name>/.../? So like /api/v3/plugin/ansible/something/.

#9 Updated by daviddavis over 1 year ago

  • Related to Story #3181: As a user, I have a roles API for published distribution base paths added

#10 Updated by daviddavis over 1 year ago

  • Related to deleted (Story #3181: As a user, I have a roles API for published distribution base paths)

#11 Updated by daviddavis over 1 year ago

  • Blocks Story #3181: As a user, I have a roles API for published distribution base paths added

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

  • Description updated (diff)

#13 Updated by bmbouter over 1 year 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?

#14 Updated by bmbouter over 1 year ago

I moved the renaming idea to its own issue: https://pulp.plan.io/issues/3532

#15 Updated by daviddavis over 1 year 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.

#16 Updated by bmbouter over 1 year ago

I think a topic this important would benefit from its own page.

#17 Updated by bmbouter over 1 year 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.

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

  • Groomed changed from No to Yes
  • Sprint Candidate changed from No to Yes

#19 Updated by daviddavis over 1 year ago

  • Subject changed from As a plugin writer, I have documentation on how to create api endpoints responsibly to As a plugin writer, I have documentation on how to create live api endpoints responsibly
  • Sprint set to Sprint 35
  • Tags Documentation added

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

  • Related to Story #3560: As a plugin writer, I can write views (at arbirary endpoints) which are discovered and registered with pulpcore. added

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

  • Blocks deleted (Story #3181: As a user, I have a roles API for published distribution base paths)

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

  • Blocks Story #3181: As a user, I have a roles API for published distribution base paths added

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

  • Sprint/Milestone set to 3.0

#24 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 35 to Sprint 36

#25 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 36 to Sprint 37

#26 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 37 to Sprint 38

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

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

#28 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 38 to Sprint 39

#29 Updated by amacdona@redhat.com over 1 year 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:
https://github.com/asmacdo/plugin_template/tree/add-plugin-writer-docs

The change should go here:
https://github.com/asmacdo/plugin_template/blob/add-plugin-writer-docs/docs/plugin-writer/reference/live-api.rst

Note, please review whats already there. I'm not sure its correct to say that this is primarily a publishing thing.

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

  • Sprint changed from Sprint 39 to Sprint 40

#31 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 40 to Sprint 41

#32 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 41 to Sprint 42

#33 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 42 to Sprint 43

#34 Updated by bmbouter about 1 year ago

  • Blocks deleted (Story #3181: As a user, I have a roles API for published distribution base paths)

#35 Updated by amacdona@redhat.com 12 months ago

  • Sprint changed from Sprint 43 to Sprint 44

#36 Updated by daviddavis 11 months ago

  • Sprint changed from Sprint 44 to Sprint 45

#37 Updated by rchan 11 months ago

  • Sprint changed from Sprint 45 to Sprint 46

#38 Updated by rchan 10 months ago

  • Sprint changed from Sprint 46 to Sprint 47

#39 Updated by rchan 9 months ago

  • Sprint changed from Sprint 47 to Sprint 48

#40 Updated by ipanova@redhat.com 8 months ago

  • Sprint deleted (Sprint 48)

#41 Updated by dkliban@redhat.com 7 months ago

  • Project changed from 27 to Pulp
  • Tags deleted (Pulp 3 MVP)

This should be part of the docs in pulpcore-plugin repo.

#42 Updated by ipanova@redhat.com 6 months ago

  • Sprint Candidate changed from Yes to No

#43 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF