Bug 1017865 - API synchronous call report example doesn't match task group management data description
API synchronous call report example doesn't match task group management data ...
Product: Pulp
Classification: Community
Component: documentation (Show other bugs)
Unspecified Unspecified
medium Severity unspecified
: ---
: 2.3.0
Assigned To: Jay Dobies
: Triaged
Depends On:
  Show dependency treegraph
Reported: 2013-10-10 12:04 EDT by mkovacik
Modified: 2013-12-09 09:29 EST (History)
4 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2013-12-09 09:29:51 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description mkovacik 2013-10-10 12:04:07 EDT
Description of problem:
There are discrepancies in fields shown in these docs pages [1][2]:
- _href
- task_group_id

[1] https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/conventions/sync-v-async.html#call-report
[2] https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/integration/rest-api/dispatch/group.html#task-group-management

Version-Release number of selected component (if applicable):
Pulp 2.2

Actual results:
Based on listing tasks from /tasks/ path [1] seems outdated

Expected results:
[1] fixed

Additional info:
# https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/conventions/sync-v-async.html#call-report
 "exception": null,
 "job_id": null,
 "task_id": "0fe4fcab-a040-11e1-a71c-00508d977dff",
 "tags": [
 "reasons": [],
 "start_time": "2012-05-17T16:48:00Z",
 "traceback": null,
 "state": "running",
 "finish_time": null,
 "schedule_id": null,
 "result": null,
 "progress": { <contents depend on the operation> },
 "response": "accepted",
 "_href": "/pulp/api/v2/tasks/0fe4fcab-a040-11e1-a71c-00508d977dff/"

# https://pulp-dev-guide.readthedocs.org/en/pulp-2.2/integration/rest-api/dispatch/group.html#task-group-management

{"_href": "/pulp/api/v2/task_groups/7744e2df-39b9-46f0-bb10-feffa2f7014b/",
  "response": "running",
  "reasons": [{"resource_type": "repository", "resource_id": "test-repo", "operation": "update"}],
  "state": "running",
  "task_id": "d6b6fe8e-ff0f-40e4-bb3c-9e547f0cc4a0",
  "task_group_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b",
  "schedule_id": null,
  "progress": {},
  "result": null,
  "exception": null,
  "traceback": null,
  "start_time": "2012-05-13T23:00:02Z",
  "finish_time": null,
  "tags": ["pulp:repository:test-repo"],
Comment 1 Michael Hrivnak 2013-10-10 12:13:05 EDT
Can you be more explicit and descriptive about what the discrepancies are? I'm not seeing it on first look.
Comment 2 mkovacik 2013-10-11 05:25:23 EDT
fields present in [1] absent in [2]:
 - job_id

fields present in [2] absent in [1]:
- task_group_id

fields with different meaning
- _href [1] points to /pulp/api/v2/tasks/
- _href [2] points to /pulp/api/v2/task_groups/

Based on listing /pulp/api/v2/tasks/ it seems [2] is more up-to-date
Comment 3 Jay Dobies 2013-10-28 09:29:25 EDT
Comment 4 Jay Dobies 2013-10-28 09:32:09 EDT
Here's what I changed:

fields present in [1] absent in [2]:
 - job_id

----- Removed this from [1], it was an old example before task groups existed.

fields present in [2] absent in [1]:
- task_group_id

----- Added this to [1] to replace job_id from above.

fields with different meaning
- _href [1] points to /pulp/api/v2/tasks/
- _href [2] points to /pulp/api/v2/task_groups/

----- I didn't touch this in this fix. The docs are correct, this is in fact what is returned. For operations that are handled in a single task, the _href refers to the task itself. For operations that *can* span multiple tasks, a list of tasks are returned and the _href for each is set to the group.

The behavior of the latter is debatable, but for the purposes of this bug, the docs are correct. If you'd like to pursue changing the values of the _hrefs, please file a new bug to start that discussion.
Comment 5 Jeff Ortel 2013-10-29 11:29:37 EDT
build: 2.3.0-0.26.beta
Comment 6 mkovacik 2013-11-04 08:13:35 EST
Checked the job_id in latest docs[1].
With regards to 2; will file a separate bug agains the API as the _href field doesn't point to a particular task item in cases where more tasks are spawned by pulp. This breaks compatibility with case when just a single task is spawned.

[1] https://pulp-dev-guide.readthedocs.org/en/latest/conventions/sync-v-async.html#call-report
Comment 7 Preethi Thomas 2013-12-09 09:29:51 EST
Pulp 2.3 released.

Note You need to log in before you can comment on or make changes to this bug.