[Pulp-dev] Pulp 3 REST API Challenges

[Milan Kovacik]

Brian,

On Tue, Apr 10, 2018 at 8:04 PM, Brian Bouterse <bbouters at redhat.com> wrote:
> These are good problem statements. I didn't understand all of the aspects of
> it, so I put some inline questions.
>
> My overall question is: are these related problems? To share my answer to
> this, I believe the first two problems are related and the third is
> separate. The classic divide and conquor approach we could use here is to
> confirm that the problems are unrelated and focus on resolving one of them
> first.

Addressing any of these issues separately influences the solution to
the rest of those therefore I believe them not to be independent.
For instance, keeping action endpoint <plug-in>importer/sync/ while
keeping POST@/repository/<abc>/version/ while addressing the plug-in
involvement absence, results in a design where plug-in configuration
objects need to exist to be passed thru as parameters to those
endpoints and causing inconsistency with plug-in specific version
creation endpoints.
At the same time we are aware of a solution that addresses all three
issues at once by a design enhancement.
What would be the motivation to enumerate the issues separately?

>
>
> On Mon, Apr 9, 2018 at 3:18 PM, Austin Macdonald <austin at redhat.com> wrote:
>>
>> Folks,
>>
>> Austin, Dennis, and Milan have identified the following issues with
>> current Pulp3 REST API design:
>>
>> Action endpoints are problematic.
>>
>> Example POST@/importers/<plugin>/sync/
>> They are non-RESTful and would make client code tightly coupled with the
>> server code.
>> These endpoints are inconsistent with the other parts of the REST API.
>
> Is self-consistency really a goal? I think it's a placeholder for
> consistency for REST since the "rest" of the API is RESTful. After reading
> parts of Roy Fielding's writeup of the definition of REST I believe "action
> endpoints are not RESTful" to be a true statement. Maybe "Action endpoints
> are problematic" should be replaced with "Action endpoints are not RESTful"
> perhaps and have the self-consistency bullet removed?

In my mind being RESTful implies consistency but I might be wrong.

>>
>> DRF is not being used as intended for action endpoints so we have to
>> implement extra code. (against the grain)
>
> I don't know much about this. Where is the extra code?

for instance, custom action endpoints need custom documentation
workarounds; see https://github.com/pulp/pulp_file/pull/60
TL;DR: working around POST@/type/ that doesn't create an instance of the type.

>
>>
>> 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?

The point here is to stress the absence of a good rule-of-a-thumb.
Currently POST at importers/<plug-in>/<abc>/sync/ and
POST@/repository/<xyz>/version/ create repository version.
Not being careful about a good design (by e.g preserving these core
endpoints), custom plug-in actions might end up being yet another
place where repository versions would be created.

>
>>
>> For direct repository version creation, plugins are not involved.
>>
>> validation correctness problem: https://pulp.plan.io/issues/3541
>> example: POST@/api/v3/repositories/<repository_id>/versions/
>
> I agree with this problem statement. In terms of scope it affects some
> plugin writers but not all.

Yet a good design wouldn't stand in the way of plug-ins that won't
need the involvement by e.g not forcing a core endpoint to require
plug-in configuration to be passed thru.


Thanks,
milan

>
>>
>> We would like to get feedback on these issues being sound and worth
>> resolving before we resume particular solution discussion[1].
>>
>> Thanks,
>> Austin, Dennis, and Milan
>>
>> [1] https://www.redhat.com/archives/pulp-dev/2018-March/msg00066.html
>>
>>
>> _______________________________________________
>> Pulp-dev mailing list
>> Pulp-dev at redhat.com
>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>
>
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>