I am running with an idea that Milan brought up. I think this will create a
simpler user experience while providing an obvious pattern to plugin
writers. This pattern will offer greater plugin control and flexibility.

Tasks that add/remove content to a repo (which creates Repository Versions)
must have plugin involvement for some plugins (detailed explanation
below).  What endpoint(s) should we use, and how can they involve plugins?

Rather than thinking of a POST that "creates RepositoryVersions" we could
instead POST to "create Tasks".

How the REST API would look:

Create a docker add task (add Docker units to a repository):
POST api/v3/tasks/docker/adds/ add_content_units=[...]

Create a file sync task
POST api/v3/tasks/file/syncs/ repository=repo_href importer=importer_href

Retrieve all tasks and optionally filter:
GET v3/tasks/?state=waiting

Retrieve python sync tasks:
GET /v3/tasks/python/syncs/

* Each POST that creates a task returns the created task synchronously,
with a created_resource field that is updated after the task runs.
* POST requests create a resource of the type that is indicated by the href.
* plugin writers create endpoints for all tasks that affect how content is
added/removed to a repo version
* core would have the opportunity to provide simple implementations that
could be used by the plugins. For example, pulpcore could provide a task
for the simple case of add/remove (which would be used by pulp_file).
* avoids verbs as action endpoints, instead using nouns as task types.
* creates an intuitive way to view tasks based on task type.
* Each Task has specific parameters that are auto-documented clearly and
* Continues pattern of "plugin writer in control, using pulpcore where it
is helpful"
* provides an obvious place for plugins to create custom endpoints
* (speculative) We could clone tasks to repeat previous actions. This would
make it easier to perform syncs on a particular repo with a particular
importer with particular sync options.

* Plugin writers have to create more endpoints
* endpoints might not be consistent between plugins
* different from Pulp 2

Detailed Problem Statement:
Currently we have a pulpcore endpoint(add/remove) and plugin defined
endpoints(sync, fancy-add, etc) that can create repository versions. All of
these endpoints return a 202 and serialize the Task that was created.

add/remove: POST to v3/repositories/<repo_uuid>/versions/
Since this is a pulpcore endpoint, it does not involve the plugin, which
causes trouble for plugins in which content units relate to other content
units. For example, it is incorrect to add a Docker Manifest if we don't
also add the Blobs that are referenced by the Manifest.

sync, etc: v3/importers/<type>/<importer_uuid>/sync/
This allows plugins to completely control the whole process, using pulpcore
tools where they are helpful. This is advantageous because plugins can
specify (including documentation) whatever POST body parameters they need
for the sync action. However, it isn't optimal to have "action" endpoints
like sync. Also, this doesn't provide a good place for plugins to define
endpoints for "rich-copy" that don't use importers.
Pulp-dev mailing list

Reply via email to