Most resources include a list of action links to provide functions not achieved through the standard HTTP methods.
<resource>
...
<actions>
<link rel="start" href="/api/collection/resource_id/start"/>
<link rel="stop" href="/api/collection/resource_id/stop"/>
...
</actions>
...
</resource>
The API invokes an action with a POST
request to the supplied URI. The body of the POST
requires an action
representation encapsulating common and task-specific parameters.
Table 7.6. Common action parameters
Element
|
Description
|
---|
async
|
true if the server responds 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.
An action also requires a Content-Type: application/xml
header since the POST
request requires an XML representation in the body content.
When the action is initiated asynchronously, the immediate 202 Accepted
response provides a link to monitor the status of the task:
POST /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="/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.
Table 7.7. Action statuses
Status
|
Description
|
---|
pending
|
Task has not yet started.
|
in_progress
|
Task is in operation.
|
complete
|
Task completed successfully.
|
failed
|
Task 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 GET
s are 301 Moved Permanently
redirected back to the target resource.
GET /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="/api/collection/resource_id/action/action_id">
<status>
<state>pending</state>
</status>
<link rel="parent" /api/collection/resource_id"/>
<link rel="replay" href="/api/collection/resource_id/action"/>
<action>
An action representation also includes some links that are identified by the rel
attribute:
Table 7.8. Action relationships
Type
|
Description
|
---|
parent
|
A link back to the resource of this action
|
replay
|
A link back to the original action URI. POSTing to this URI causes the action to be re-initiated
|