[Pulp-dev] Pulp 3 REST API Challenges

Wed Apr 11 03:53:02 UTC 2018

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

This comment makes it sound like the Tasks proposal is forcing REST on the
design, but IMO our design is a great fit for REST. The fact is that Tasks
are resources no matter what, nothing fake about them. Whether we treat
them like all other resources is an open question. IMO we should only make
the API more RESTful if that also makes the API better.

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

That is not how it is designed. All object CRUD would stay where it is. We
are trying to focus on the problems and goals for now, but when the time
comes, I'll be sure to highlight this part of the design.

My overall question is: are these related problems?

When our goal is consistency, problems of related endpoints become related.
Jeff's earlier comment applies: "Looks like half of the plugins will need
to participate in creating repository versions (outside of sync). The API
design should take a consistent approach to creating repository versions (
*add* *and* *sync*)."

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

Milan's "In my mind being RESTful implies consistency" +1. I value
consistency, REST is just one way to get it.

I think we are close to being able to move forward. It seems like there is
broad agreement about the goals/problems, with minor semantic differences.

On Tue, Apr 10, 2018 at 6:44 PM, Jeff Ortel <jortel at redhat.com> wrote:

>
>
> On 04/10/2018 04:15 PM, Dennis Kliban wrote:
>
> On Tue, Apr 10, 2018 at 2: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.
>>
>>
> I don't think all 3 are related problems. The motivation for grouping all
> together is that a subset of the action endpoints from problem 1 are used
> to create repository versions and Problem 3 is a problem with the
> repository version creation API.
>
>
>>
>> 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?
>>
>
> +1 to "Action endpoints are not RESTful"
> +1 to removing the self-consistency language
>
>
>>
>>>    - 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?
>>
>>
>>>
>>>    - 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.
>
>
>>
>>>    - 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.
>>
>
> I think it affects all plugin writers. Even the File plugin needs to
> provide some validation when creating a repository version. Right now you
> can add a FileContent with the same relative path as another FileContent in
> the repository version. This should not be possible because it's not a
> valid combination of FileContent units in the same repository version.
>
>
> Not necessarily.  Two files with the same relative path will have
> different digest (different content).  The assumption that they both cannot
> be in the same repository makes assumptions about how the repository is
> used which I don't think is a good idea.  Image two different versions of
> abc.iso.
>
>
>
>>
>>
>>> 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
>>
>>
>
>
> _______________________________________________
> Pulp-dev mailing listPulp-dev at redhat.comhttps://www.redhat.com/mailman/listinfo/pulp-dev
>
>
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180410/9cb1529c/attachment.htm>