Project

Profile

Help

Story #3473

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

Added by daviddavis over 2 years ago. Updated 16 days ago.

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

0%

Estimated time:
Platform Release:
Groomed:
Yes
Sprint Candidate:
No
Tags:
Documentation
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.CLOSED - CURRENTRELEASE

<a title="Actions" class="icon-only icon-actions js-contextmenu" href="#">Actions</a>

History

#1 Updated by daviddavis over 2 years ago

  • Tags Pulp 3, Pulp 3 MVP added

#2 Updated by daviddavis over 2 years 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 2 years ago

  • Description updated (diff)

#4 Updated by dalley over 2 years ago

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

#5 Updated by daviddavis over 2 years 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 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.

#7 Updated by amacdona@redhat.com over 2 years 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 2 years 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 2 years ago

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

#10 Updated by daviddavis over 2 years ago

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

#11 Updated by daviddavis over 2 years 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 2 years ago

  • Description updated (diff)

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

#14 Updated by bmbouter over 2 years ago

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

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

#16 Updated by bmbouter over 2 years ago

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

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

#18 Updated by amacdona@redhat.com over 2 years ago

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

#19 Updated by daviddavis over 2 years 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 2 years 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 2 years 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 2 years 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 2 years ago

  • Sprint/Milestone set to 3.0.0

#24 Updated by rchan over 2 years ago

  • Sprint changed from Sprint 35 to Sprint 36

#25 Updated by rchan about 2 years ago

  • Sprint changed from Sprint 36 to Sprint 37

#26 Updated by rchan about 2 years ago

  • Sprint changed from Sprint 37 to Sprint 38

#27 Updated by amacdona@redhat.com about 2 years ago

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

#28 Updated by rchan about 2 years ago

  • Sprint changed from Sprint 38 to Sprint 39

#29 Updated by amacdona@redhat.com about 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:
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 about 2 years ago

  • Sprint changed from Sprint 39 to Sprint 40

#31 Updated by rchan about 2 years ago

  • Sprint changed from Sprint 40 to Sprint 41

#32 Updated by rchan almost 2 years ago

  • Sprint changed from Sprint 41 to Sprint 42

#33 Updated by rchan almost 2 years ago

  • Sprint changed from Sprint 42 to Sprint 43

#34 Updated by bmbouter almost 2 years ago

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

#35 Updated by amacdona@redhat.com almost 2 years ago

  • Sprint changed from Sprint 43 to Sprint 44

#36 Updated by daviddavis almost 2 years ago

  • Sprint changed from Sprint 44 to Sprint 45

#37 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 45 to Sprint 46

#38 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 46 to Sprint 47

#39 Updated by rchan over 1 year ago

  • Sprint changed from Sprint 47 to Sprint 48

#40 Updated by ipanova@redhat.com over 1 year ago

  • Sprint deleted (Sprint 48)

#41 Updated by dkliban@redhat.com over 1 year 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 over 1 year ago

  • Sprint Candidate changed from Yes to No

#43 Updated by bmbouter over 1 year ago

  • Tags deleted (Pulp 3)

#44 Updated by ChristopherLightner 16 days ago

wrote:

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".

No, Pulp Plugin API is versioned separately from Pulp Core you are wrong. Issue is in main plugin writer, check in "advanced". Believe me, I know , I worked with Ansible plugin for my thesis project

lab reports: https://writemyessaysonline.com

Please register to edit this issue

Also available in: Atom PDF