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

[Michael Hrivnak]

On Mon, Oct 23, 2017 at 11:43 AM, Brian Bouterse <bbouters at redhat.com>
wrote:

> There is a lot of good discussion here. See inline about the motivation to
> not add additional fields to the task model.
>
> 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.
>>
>> 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 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?
>>
>
> This is similar to what we did on Pulp2 where task status field semantics
> are different task by task. In other words this field's usage and data
> differs depending on the task type making it like a mutating field. This
> was a real challenge for users in Pulp2 because the data semantics and
> format are all different which prevents users from handling that field
> generically. Currently all fields on a task status are semantically
> concrete. I think we should continue to do that.
>

 I completely agree. A key aspect of REST, which we have not achieved with
Pulp 2, is depending on media types to express what each returned link
references. As an example, HAL is one common way to do this:

http://stateless.co/hal_specification.html

In any scenario where we included links to created resources, I would
expect those links to come with enough information for a client to
understand what type of resource the link references. That's a standard
REST practice that would be especially useful in this scenario to ensure
that task status representations are semantically concrete.

-- 

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/b12eae2d/attachment.htm>