Delete Completed Job Status

The Delete Completed Job Status operation deletes the job status and results associated with a job that has ended. This operation is supported using the BCPii interface.

HTTP method and URI

DELETE /api/jobs/{job-id}

In this request, the URI variable {job-id} is the identifier of an asynchronous job associated with the API user, as provided by the operation that initiated the job.

Description

The Delete Completed Job Status operation deletes the job status and results associated with a job that has ended.

If the job designated by the request URI has completed or has been canceled, its ending status and results are deleted from the HMC and status code 204 (No Content) is returned to the client.

If the job has not yet ended (i.e. is still running, or cancellation has been requested but is still pending), the operation fails and HTTP status code 409 (Conflict) is returned to the client.

If the URI does not designate a job associated with the API user, or if the job's status has already been deleted (either explicitly, or due to expiration of the status retention interval), HTTP status code 404 (Not Found) is returned to the client.

Authorization requirements

This operation has the following authorization requirement:
  • The job URI must designate an asynchronous job associated with the API user or for the BCPii interface the requesting partition.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

The following HTTP status codes are returned for the indicated operation-specific errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
2 For a job that was initiated using the BCPii interface the request does not contain or contains an invalid X-API-Target-Name header value.
404 (Not Found) 1 The URI does not designate an asynchronous job associated with the API user.
409 (Conflict) 40 The URI designates an asynchronous job that has not ended.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Usage notes

  • This operation is defined to operate only on jobs that have ended, i.e. have a status field with value "complete" or "canceled". As a result, this operation cannot be used to cancel an in-progress asynchronous operation. See Cancel Job for information pertaining to job cancellation.
  • Once an asynchronous job has ended, job status is retained by the HMC for a minimum of 4 hours to allow the client application time to retrieve the results, but this status and results are not held indefinitely. At the expiration of the retention interval, job status is deleted as if the Delete Completed Job Status operation were called.

Example HTTP interaction

Figure 1. Delete Completed Job Status: Request
DELETE /api/jobs/86e44546-107f-11e1-bde0-0010184c8334 HTTP/1.1
x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4rymqa8ktzjep7dbyrll0k
Figure 2. Delete Completed Job Status: Response
204 No Content
date: Wed, 16 Nov 2011 18:19:35 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>