<div dir="ltr">Regarding the first bullet point, I think it’s an admirable goal but I worry that aiming for REST purity can cause us to do some funny things like defining fake resources that are really just actions on existing resources. It’s a bit like trying to be purely OO in Python and having to wrap a function in a fake class. I think this is what I found unappealing about the plugin tasks proposal. <div><br></div><div>You mention consistency of REST but I found the plugin tasks proposal to lack consistency in certain areas. For example, some deletes are handled on resources (distributions, artifacts, etc) while other deletions would live in the tasks namespace (repos, publishers, etc). So I am not sure how moving to a strictly RESTful API solves all our consistency problems.<div><br></div><div>In my experience of working on RESTful APIs, we’ve always had to resort to using action verbs so I’d be interested in seeing some other applications that are purely RESTful if anyone has some examples.</div></div></div><div class="gmail_extra"><br clear="all"><div><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div><br></div><div>David<br></div></div></div></div></div></div></div></div>
<br><div class="gmail_quote">On Tue, Apr 10, 2018 at 4:08 PM, Milan Kovacik <span dir="ltr"><<a href="mailto:mkovacik@redhat.com" target="_blank">mkovacik@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Brian,<br>
<span class=""><br>
On Tue, Apr 10, 2018 at 8:04 PM, Brian Bouterse <<a href="mailto:bbouters@redhat.com">bbouters@redhat.com</a>> wrote:<br>
> These are good problem statements. I didn't understand all of the aspects of<br>
> it, so I put some inline questions.<br>
><br>
> My overall question is: are these related problems? To share my answer to<br>
> this, I believe the first two problems are related and the third is<br>
> separate. The classic divide and conquor approach we could use here is to<br>
> confirm that the problems are unrelated and focus on resolving one of them<br>
> first.<br>
<br>
</span>Addressing any of these issues separately influences the solution to<br>
the rest of those therefore I believe them not to be independent.<br>
For instance, keeping action endpoint <plug-in>importer/sync/ while<br>
keeping POST@/repository/<abc>/<wbr>version/ while addressing the plug-in<br>
involvement absence, results in a design where plug-in configuration<br>
objects need to exist to be passed thru as parameters to those<br>
endpoints and causing inconsistency with plug-in specific version<br>
creation endpoints.<br>
At the same time we are aware of a solution that addresses all three<br>
issues at once by a design enhancement.<br>
What would be the motivation to enumerate the issues separately?<br>
<span class=""><br>
><br>
><br>
> On Mon, Apr 9, 2018 at 3:18 PM, Austin Macdonald <<a href="mailto:austin@redhat.com">austin@redhat.com</a>> wrote:<br>
>><br>
>> Folks,<br>
>><br>
>> Austin, Dennis, and Milan have identified the following issues with<br>
>> current Pulp3 REST API design:<br>
>><br>
>> Action endpoints are problematic.<br>
>><br>
>> Example POST@/importers/<plugin>/sync/<br>
>> They are non-RESTful and would make client code tightly coupled with the<br>
>> server code.<br>
>> These endpoints are inconsistent with the other parts of the REST API.<br>
><br>
> Is self-consistency really a goal? I think it's a placeholder for<br>
> consistency for REST since the "rest" of the API is RESTful. After reading<br>
> parts of Roy Fielding's writeup of the definition of REST I believe "action<br>
> endpoints are not RESTful" to be a true statement. Maybe "Action endpoints<br>
> are problematic" should be replaced with "Action endpoints are not RESTful"<br>
> perhaps and have the self-consistency bullet removed?<br>
<br>
</span>In my mind being RESTful implies consistency but I might be wrong.<br>
<span class=""><br>
>><br>
>> DRF is not being used as intended for action endpoints so we have to<br>
>> implement extra code. (against the grain)<br>
><br>
> I don't know much about this. Where is the extra code?<br>
<br>
</span>for instance, custom action endpoints need custom documentation<br>
workarounds; see <a href="https://github.com/pulp/pulp_file/pull/60" rel="noreferrer" target="_blank">https://github.com/pulp/pulp_<wbr>file/pull/60</a><br>
TL;DR: working around POST@/type/ that doesn't create an instance of the type.<br>
<span class=""><br>
><br>
>><br>
>> We don't have a convention for where plug-in-specific, custom repository<br>
>> version creation endpoints.<br>
>><br>
>> example POST@/api/v3/<where?>/docker/<wbr>add/<br>
>> needs to be discoverable through the schema<br>
><br>
> What does discoverable via the schema ^ mean? Aren't all urls listed in the<br>
> schema?<br>
><br>
> I think of ^ problem somewhat differently. Yes all urls need to be<br>
> discoverable (a REST property), but isn't it more of an issue that the urls<br>
> which produce repo versions can't be identified distinctly from any other<br>
> plugin-contributed url? To paraphrase this perspective: making a repo<br>
> version is strewn about throughout the API in random places which is a bad<br>
> user experience. Is that what is motivation url discovery?<br>
<br>
</span>The point here is to stress the absence of a good rule-of-a-thumb.<br>
Currently POST@importers/<plug-in>/<abc><wbr>/sync/ and<br>
POST@/repository/<xyz>/<wbr>version/ create repository version.<br>
Not being careful about a good design (by e.g preserving these core<br>
endpoints), custom plug-in actions might end up being yet another<br>
place where repository versions would be created.<br>
<span class=""><br>
><br>
>><br>
>> For direct repository version creation, plugins are not involved.<br>
>><br>
>> validation correctness problem: <a href="https://pulp.plan.io/issues/3541" rel="noreferrer" target="_blank">https://pulp.plan.io/issues/<wbr>3541</a><br>
>> example: POST@/api/v3/repositories/<<wbr>repository_id>/versions/<br>
><br>
> I agree with this problem statement. In terms of scope it affects some<br>
> plugin writers but not all.<br>
<br>
</span>Yet a good design wouldn't stand in the way of plug-ins that won't<br>
need the involvement by e.g not forcing a core endpoint to require<br>
plug-in configuration to be passed thru.<br>
<br>
<br>
Thanks,<br>
milan<br>
<div class="HOEnZb"><div class="h5"><br>
><br>
>><br>
>> We would like to get feedback on these issues being sound and worth<br>
>> resolving before we resume particular solution discussion[1].<br>
>><br>
>> Thanks,<br>
>> Austin, Dennis, and Milan<br>
>><br>
>> [1] <a href="https://www.redhat.com/archives/pulp-dev/2018-March/msg00066.html" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>archives/pulp-dev/2018-March/<wbr>msg00066.html</a><br>
>><br>
>><br>
>> ______________________________<wbr>_________________<br>
>> Pulp-dev mailing list<br>
>> <a href="mailto:Pulp-dev@redhat.com">Pulp-dev@redhat.com</a><br>
>> <a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/pulp-dev</a><br>
>><br>
><br>
><br>
> ______________________________<wbr>_________________<br>
> Pulp-dev mailing list<br>
> <a href="mailto:Pulp-dev@redhat.com">Pulp-dev@redhat.com</a><br>
> <a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/pulp-dev</a><br>
><br>
<br>
______________________________<wbr>_________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/<wbr>mailman/listinfo/pulp-dev</a><br>
</div></div></blockquote></div><br></div>