18 ACTION RESOURCE & REPRESENTATION

The action resource can be used to obtain the detailed domain object action representation §C18.2 for a particular domain object instance or for a particular domain service. This provides a description of the action only; to invoke it, the object action invoke sub-resource §C18.2 is used.

This resource is typically requested as a result of following a link from the domain object representation §C14.4.

The endpoint URL for this resource for an action on a domain service is:

/services/{serviceId}/actions/{actionId}

where:

  • {serviceId} is a unique identifier for the service

  • {actionId} is the action identifier

The endpoint URL for this resource for an action on a domain object is:

/objects/{domainType}/{instanceId}/actions/{actionId}

where:

  • {domainType} uniquely identifies the object’s type, and

  • {instanceId} uniquely identifies an object instance of that type

  • {actionId} is the action identifier

18.1 HTTP GET

Obtain a detailed representation of an action §C18.2.

18.1.1 GET Request

18.1.1.1 Query String

  • x-ro-domain-model (optional, §A3.1)

    • "simple"

    • "formal"

18.1.1.2 Headers

  • Accept

    • application/json

    • application/json;profile="…​/object-action"

18.1.1.3 Body

  • N/A

18.1.2 GET Success Response

As per §C13.1 (200), returning an object action representation §C18.2.

18.2 Representation

The domain object action representation provides full details of an action on a domain object instance, and provides links to resources that can invoke the action (if allowed).

The Content-Type for the representation is:

application/json;profile=".../object-action"

The links from the object action representation to other resources are as shown in the diagram below:

figure 11
Figure 1. OBJECT ACTION REPRESENTATION

For example, the representation of Order’s submit action might be:

{
  "id": submit",
  ...
  "parameters": {
      ...
  },
  "disabledReason": ...,
  "links": [ {
      "rel": "self",
      "href": "http://~/objects/ORD/123/actions/submit",
      "type": "application/json;profile=\".../object-action\"",
      "method": "GET"
    }, {
      "rel": ".../invoke;action=\"submit\"",
      ...
    }, {
      "rel": "up",
      ...
    } ...
  ],
  "extensions": { ... }
}

where:

JSON-Property Description

links

list of links to resources.

links[rel=self]

link to a resource that can generate this representation.

id

the action ID, to use when building templated URIs parameters map of parameters; discussed below §C18.2.1

disabledReason

(optional) if populated then indicates the reason why the action cannot be invoked.

links[rel=…​/invoke]

(optional) is a link to invoke the action (if it is not disabled), §C18.2.2.

links[rel=up]

link to the object that is the owner of this action.

extensions

additional metadata about the resource

Both the "links" and the "extensions" json-properties may contain domain model information; this is discussed in §C18.2.3.

Restful Objects defines no standard child properties for the "extensions" json-property (other than any domain model information). Implementations are free to add further links/json-properties to both "links" and "extensions" as they require.

18.2.1 Action parameters

The action resource lists the parameter details in the "parameters" list:

"parameters": {
  "paramName1": {   (1)
    "choices": [ {
        "rel": ".../choice;action=\"action\";param=\"paramName1\"",
        ...
      }, {
        "rel": ".../choice;action=\"action\";param=\"paramName1\"",
        ...
      }, {
        "rel": ".../choice;action=\"action\";param=\"paramName1\"",
        ...
      } ...
    ],
    "default": {
      "rel": ".../default;action=\"action\";param=\"paramName1\"",
      ...
    },
    "links": [ ... ],
    "extensions": { ... }
  },
  "paramName2": { (1)
    "choices": [ ... ],
    "default": { ... },
    "links": [ ... ],
    "extensions": { ... }
  },
  "paramName3": { (1)
    "choices": [ ... ],
    "default": { ... },
    "links": [ ... ],
    "extensions": { ... }
  },
  ...
]
1 paramName1, paramName2, paramName3 are the ids of the parameters, used as a unique key in the "parameters" map

This id is also as used as the key in argument maps §A2.9.2, with their value being the following map:

JSON-Property Description

choices

an optional list of choices for the parameter argument

default

an optional value/link to act as the default for the parameter argument

links

list of links to other resources related to the action parameter

extensions

additional metadata about the action parameter

The rel values for choices and defaults specify both the action and parameter name in order to distinguish from other links.

The "links" and/or "extensions" json-property may hold domain model metadata; see §C18.2.3.

18.2.2 Action invocation

If the action can be invoked then the "rel" = "invoke" link will contain a link by which the action can be invoked. This will be either a GET, a PUT or a POST dependent upon the action’s semantics.

If the implementation can determine that the action is ‘query-only’, then a GET link should be provided:

{
  ...
  "links": [ {
      "rel": ".../invoke;action=\"recentOrder\"",
      "href": "http://~/objects/CUS/001/actions/recentOrder/invoke",
      "type": "application/json;profile=\".../action-result\"",
      "arguments": {
        ...
       },
      "method": "GET"
    }, ...
  ], ...
}

If the implementation can determine that the action is idempotent then a PUT link will be provided:

{
  ...
  "links": [ {
      "rel": ".../invoke;action=\"makeRush\"",
      "href": "http://~/objects/ORD/123/actions/makeRush/invoke",
      "type": "application/json;profile=\".../action-result\"",
      "arguments": {
        ...
      },
      "method": "PUT"
    }, ...
  ], ...
}

Finally, if the action to be invoked is neither query-only nor idempotent,(or if the implementation is unable to determine this), then a POST link will be provided:

{
  ...
  "links": [ {
      "rel": ".../invoke;action=\"submit\"",
      "href": "http://~/objects/ORD/123/actions/submit/invoke",
      "type": "application/json;profile=\".../action-result\"",
      "arguments": {
        ...
      },
      "method": "POST"
    }, ...
  ], ...
}

"type" property

The "type" json-property always indicates that the urn:org.restfulobjects:repr-types/action-result representation will be returned §C19.4.

"arguments" property

The "arguments" json-property has placeholders for the values of each of the arguments. Commonly, these values will be null - it is up to the client to determine the value to use when invoking the action. However the server may provide a default value.

To summarize:

JSON-Property Description

link[…​/rel=invoke]

link to invoke the action; not included if the action is disabled

If the action may NOT be invoked (for example because of the status of the object to which the action applied), then the representation should include a "disabledReason" json-property (or just the literal "disabled") why the action cannot be invoked:

{
  ...
  "disabledReason": "Cannot place order because customer has been blacklisted",
  ...
}

where:

JSON-Property Description

disabledReason

indicates the reason why the action cannot be invoked; only included if the action is disabled.

18.2.3 Domain model information (for action)

Domain model information is available for both the action itself and also for each of the action parameters. In both cases the information is either under the "links" or under the "extensions" json-properties.

18.2.3.1 Simple scheme

Implementations that support the simple scheme provide extra data about the action in the "extensions" json-properties.

For example:

"extensions": {
  "friendlyName": "Place order",
  "description": "Place a new order",
  "returnType": ...
  "elementType": ... (1)
  "pluralForm": ...  (1)
  "hasParams": true
}
1 if returnType is 'list' or 'set'

In addition, such implementations may also provide extra data about each action parameter in that parameter’s own "extensions" json-property.

For example:

"parameters": {
  "product": {
    ...
    "extensions": {
      "friendlyName": "Product",
      "description": "The product being ordered",
      "returnType": ...,
      "optional": false,
      "format": ...,    (1)
      "maxLength": ..., (1)
      "pattern": ...    (1)
    }
  },
  ...
}
1 for string params only

See §A3.1.1 for the full definitions of these json-properties. Implementations may also provide their own extensions.

18.2.3.2 Formal scheme

Implementations that support the formal scheme §A3.1.2 provide several additional links about the action in the "links" json-property.

For example:

"links": [ {
    "rel": ".../returntype",
    "href": "http://~/domain-types/x.OrderReceipt",
    "type": "application/json;profile=\".../domain-type\"",
    "method": "GET"
  }, {
     "rel": "describedby",
     "href": "http://~/domain-types/ORD/actions/submit",
     "type": "application/json;profile=\".../type-action\"",
     "method": "GET"
   }, ...
}

In addition, implementations supporting the formal scheme may also provide extra data about each action parameter in that parameter’s own "links" json-property.

For example:

"parameters": {
  "product": {
    ...
    "links": [ {
      "rel": "describedby",
      "href": "http://~/domain-types/ORD/actions/submit/params/product",
      "type": "application/json;profile=\".../action-param-description\"",
      "method": "GET"
      }, ...
    ]
  }, ...
}