[Pulp-dev] [pulp 3] proposed change to publishing REST api

[Dennis Kliban]

On Mon, Oct 23, 2017 at 10:55 AM, Michael Hrivnak <mhrivnak at redhat.com>
wrote:

> Unless the publication can be created before the response is returned, the
> response code will need to still be 202.
>
> As for the path, either way seems workable, although I have two
> hesitations about POSTing to publications/.
>
> 1) Normally in REST when a user creates a resource via POST to a
> collection endpoint, they are expected to provide a representation of the
> new resource, even if it is only partial. In the case of initiating a
> publish task, we do not want the user to provide any part of the new
> publication's state. We only want the user to optionally provide a bit of
> information about *how* to create a new publication. Should the publication
> be incremental or not? Which repo version should be published? etc. The
> difference may seem subtle, but I think it's important.
>
> 2) The act of creating a publication may also change state of other
> resources, and not only subordinate resources such as a publication
> artifact. For example, if there is a Distribution with auto_update set to
> True, its state will be changed by a publish task. That could be seen as an
> unexpected side effect when merely POSTing to a publications/ endpoint.
> When an operation affects state across multiple resources and resource
> types, that's usually a good time to use a "controller" type endpoint that
> is specific to the operation.
>

We should probably reevaluate the value of 'auto_update' on a Distribution.
Information about distributions that need to be updated can be passed in
the body of the POST to publications/. This way the user explicitly
instructs Pulp to perform the update.


>
> Our asynchronous tasks will often need to create one or more resources. A
> publish task creates a publication. An upload-related task may create one
> or more content units. A sync/associate/unassociate task will create a new
> repository version. New resources are the output of those tasks. However
> each of those tasks will sometimes not create any resources, such as when
> an equivalent resource already exists. Creating resources is a common
> characteristic of tasks, so it would make sense to report that in a
> standard part of the task status.
>

A repository version would probably be it's own REST resource. So you would
perform a POST to repositories/foo/versions/ with information about what
should be done to create a new version: sync with a particular importer or
associate/unassosiate content.



> A task status should not include an exhaustive list of every resource
> created. For example, a publish task should not include a reference to
> every metadata artifact it made. It would be sufficient to include a
> reference to the publication, the task's primary output, which then can be
> used to reference subordinate resources.
>
> On a task status representation, this could be included in a field called
> "created_resources", "output", "return_value", or similar.
>
> Thoughts on that idea?
>
> On Fri, Oct 20, 2017 at 11:27 AM, Mihai Ibanescu <mihai.ibanescu at gmail.com
> > wrote:
>
>> That seems sensible, and in line with REST's mantra of "nouns in resource
>> URLs, not verbs".
>>
>> On Thu, Oct 19, 2017 at 3:27 PM, Dennis Kliban <dkliban at redhat.com>
>> wrote:
>>
>>> @jortel and I have been discussing[0] how a user should find out what
>>> publication was created after a request is made to
>>> http://localhost:8000/api/v3/repositories/foo/publishers/exa
>>> mple/bar/publish/
>>>
>>> I propose that we get rid of the above URL from our REST API and add
>>> ability to POST to http://localhost:8000/api/v3/r
>>> epositories/foo/publishers/example/bar/publications/ instead. The
>>> response would be a 201. Each publication would have a task associated with
>>> it.
>>>
>>> This work would probably be done by whoever picks up issue 3033[1].
>>>
>>> [0] https://pulp.plan.io/issues/3035
>>> [1] https://pulp.plan.io/issues/3033
>>>
>>> _______________________________________________
>>> 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
>>
>>
>
>
> --
>
> Michael Hrivnak
>
> Principal Software Engineer, RHCE
>
> Red Hat
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20171023/d6d1df68/attachment.htm>