[Pulp-dev] Pulp 3 REST API Challenges

[Austin Macdonald]

>
>
>>>>    - We don't have a convention for where plug-in-specific, custom
>>>>    repository version creation endpoints.
>>>>    - example POST@/api/v3/<where?>/docker/add/
>>>>       - needs to be discoverable through the schema
>>>>
>>>> What does discoverable via the schema ^ mean? Aren't all urls listed in
>>> the schema?
>>>
>>> I think of ^ problem somewhat differently. Yes all urls need to be
>>> discoverable (a REST property), but isn't it more of an issue that the urls
>>> which produce repo versions can't be identified distinctly from any other
>>> plugin-contributed url? To paraphrase this perspective: making a repo
>>> version is strewn about throughout the API in random places which is a bad
>>> user experience. Is that what is motivation url discovery?
>>>
>>>
>>
>> Yes. I envision a CLI that can discover new plugin
>> repository-version-creating functionality without having to install new
>> client packages. Allowing plugin writers to add endpoints in arbitrary
>> places for creating repository versions will make it impossible for the
>> client to know what all the possible ways of creating a repository version
>> are.
>>
>>
>> Currently plugins can provide one (or more) arbitrary endpoints to
>> perform sync which is one form of creating a repository version.  How is
>> the endpoint for creating a version by adding content any different?
>>
>>
> I don't understand the question.
>
> Right now plugin writers can add REST API endpoints that create repository
> versions anywhere they want. This means the client has to inspect all of
> the API schema to find all the different ways to create a repository
> version. I would like to make this discovery process simpler for the
> client. It would be best if the client could learn about all the ways to
> create a repository version by making a single request to the API.
>

"Custom repository version creation endpoints need to be discoverable
through the schema."

We have some different ideas for how to implement this goal, and I think
that is coloring our perception of the problem as well. The statement is
vague, but we chose it so we could show what we agree on despite having
subtly different views.

The weakest interpretation of the statement is that every API endpoint is
documented in the schema. I doubt that anyone would disagree with that. In
case it isn't clear already, I want to restate that the scope of this point
is limited to endpoints that create repository versions and publications.
(sync, add, publish, complex copy, etc). Within that scope, I look at
"discoverability" as related to the consistency issue.

If we have a logical, consistent API, then users (including client users)
should be able to guess what the endpoint (or command) should be for a
given use case. This also includes the need for docs readers to have a good
idea where to find their information. That would obviously be difficult to
do with these endpoints spread all around the API. Dennis takes this a step
farther, suggesting that *any* action that creates a repository version,
regardless of plugin should be on a single endpoint. I suggest that
grouping them by plugin is enough. Obviously, this gets into the
implementation details a bit, so I don't want to get too much in the weeds
until we are back to discussing concrete proposals.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180411/b4cd29b5/attachment.htm>