Synchronous and Asynchronous Calls

Overview

Pulp uses an advanced task queueing system that detects and avoids concurrent operations that conflict. All REST API calls are managed through this system. Any REST API will return one of three responses:

  • Success Response - 200 OK or a 201 CREATED
  • Postponed Response - 202 ACCEPTED
  • Conflict Response - 409 CONFLICT

A success response indicates no conflicts were detected and the REST call executed. This is what is typically expected from a REST API call.

A postponed response indicates that some portion of the command has been queued to execute asynchronously. In this case a Call Report or a Group Call Report will be returned with the results of the synchronously executed portion of the command.

When a single task is queued or a task with follow up tasks, such as a publish after a sync or unbind consumers after repo delete, a Call Report is returned. The Call Report will contain a list of spawned tasks.

When some number of related tasks are queued, and it is useful to track the state of all of them together, a Group Call Report is returned.

More information on retrieving and displaying task information can be found in the Task Management API documentation.

A conflict response indicates that a conflict was detected that causes the call to be unserviceable now or at any point in the future. An example of such a situation is the case where an update operation is requested after a delete operation has been queued for the resource. The body of this response is Pulp’s standard exception format including the reasons for the response.

Call Report

A 202 ACCEPTED response returns a Call Report JSON object as the response body that has the following fields:

  • result (Object) - the return value of the call, if any
  • error (Object) - error details if an error occurred. See Error Details.
  • spawned_tasks (array) - list of references to tasks that were spawned. Each task object contains the relative url to retrieve the task and the unique ID of the task.

Example Call Report:

{
 "result": {},
 "error": {},
 "spawned_tasks": [{"_href": "/pulp/api/v2/tasks/7744e2df-39b9-46f0-bb10-feffa2f7014b/",
                    "task_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b" }]
}

Group Call Report

A 202 ACCEPTED response returns a Group Call Report JSON object as the response body that has the following fields:

  • _href - Path to the root of task group resource. However, this API endpoint currently returns 404 in all cases. You can append state-summary/ to the URL and perform a GET request to retrieve a Cancelling Tasks in a Task Group.
  • group_id - UUID of the group that all the dispatched tasks belong to.

Example Group Call Report:

{
    "_href": "/pulp/api/v2/task_groups/16412fcb-06fa-4caa-818b-b103e2a9bf44/",
   "group_id": "16412fcb-06fa-4caa-818b-b103e2a9bf44"
}