8.3.8. Actions

Most resources include a list of action links.

<{resource}>
    ...
    <actions>
        <link rel="start" href="/rhevm-api/{collection}/{resource_id}/start"/>
        <link rel="stop" href="/rhevm-api/{collection}/{resource_id}/stop"/>
        ...
    </actions>
    ...
</resource>

An action is invoked with a POST request to the supplied URI. The body of the POST requires an action representation encapsulating common and/or task-specific parameters. Common action parameters include:

`async`	`true` if the server should respond immediately with `202 Accepted` and an action representation contains a `href` link to be polled for completion.
`grace_period`	a grace period in milliseconds, which must expire before the action is initiated.

Individual actions and their parameters are documented in the individual resource type's documentation. Some parameters are mandatory for specific actions and their absence is indicated with a fault response.

When the action is initiated asychronously, the immediate 202 Accepted response provides a link to monitor the status of the task:

POST /rhevm-api/{collection}/{resource_id}/{action} HTTP/1.1
Content-Type: application/xml
Accept: application/xml

<action>
    <async>true</async>
</action>

HTTP/1.1 202 Accepted
Content-Type: application/xml

<action id="{action_id}"
  href="/rhevm-api/{collection}/{resource_id}/{action}/{action_id}">
    <async>true</async>
    ...
<action>

A subsequent GET on the action URI provides an indication of the status of the asynchronous task:

`PENDING`	task has not yet started.
`IN_PROGRESS`	task is in flight.
`COMPLETE`	task has completed successfully.
`FAILED`	task has failed. The returned `action` representation would contain a `fault` describing the failure.

Once the task has completed, the Action is retained for an indeterminate period. Once this has expired, subsequent GETs are 301 Moved Permanently redirected back to the target resource.

GET /rhevm-api/{collection}/{resource_id}/{action}/{action_id} HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<action id="{action_id}"
  href="/rhevm-api/{collection}/{resource_id}/{action}/{action_id}">
    <status>{PENDING|IN_PROGRESS|COMPLETE|FAILED}</status>
    <link rel="parent" /rhevm-api/{collection}/{resource_id}"/>
    <link rel="replay" href="/rhevm-api/{collection}/{resource_id}/{action}"/>
<action>

An action representation also includes some links that are identified by the rel attribute:

`parent`	A link back to the resource of this action
`replay`	A link back to the original action URI. POSTing to this URI will causing the action to be re-initiated