13 RESPONSE SCENARIOS

When a domain object resource is invoked, one of several responses can occur. These can be distinguished by the HTTP status return code

  • 200 – Request succeeded, and generated a representation

  • 201 – Request succeeded, and generated a representation of a new object

  • 204 – Request succeeded, but generated no representation; or validation succeeded

  • 400 – Syntactically invalid request

  • 403 – Forbidden (user not authorised to modify the resource)

  • 404 – Object or object member not found or not visible

  • 405 – Method not valid for the resource

  • 406 – Client accepts only media types not generated by resource.

  • 412 – Pre-condition failed (object changed by another user)

  • 422 – Validation failed

  • 428 – Required precondition header missing

  • 500 – Domain logic failed

In addition, a 401 code may be returned for any resource if the user’s credentials are invalid (that is, they have not authenticated themselves).

The following indicates which codes may be returned by a resource:

Method Res. Repr. 200 201 204 400 403 404 405 406 412 422 428 500

Service

GET

§C15

§B11

y

y

y

y

y

Object

GET

§C14.1

§C14.4

y

y

y

y

y

PUT

§C14.2

--

y

y

y

y

y

y

y

y

y

DELETE

§C14.3

--

y

y

y

y

y

y

y

y

y

y

Prop’y

GET

§C16.1

§C16.4

y

y

y

y

y

PUT

§C16.2

--

y

y

y

y

y

y

y

y

y

DELETE

§C16.3

--

y

y

y

y

y

y

y

y

y

Coll’n

GET

§C17.1

§C17.5

y

y

y

y

y

PUT

§C17.2

--

y

y

y

y

y

y

y

y

y

y

POST

§C17.3

--

y

y

y

y

y

y

y

y

y

y

DELETE

§C17.4

--

y

y

y

y

y

y

y

y

y

Action

GET

§C18.1

§C18.2

y

y

y

y

y

y

Action
invoke

GET

§C19.1

§B11
§B12
§C14.4

y

y

y

y

y

y

y

PUT

§C19.2

--

y

y

y

y

y

y

y

y

y

y

POST

§C19.3

--

y

y

y

y

y

y

y

y

y

y

y

Objects

POST

§B9.1

§C14.4

y

y

y

y

y

For a given status code, the specific headers and body returned by these resources vary little between the different resources; this is especially so for the failure scenarios (4xx and 5xx).

This section (§C13) describes all the responses irrespective of the resource called. Sections §C14 to §C18.2 identify the various request/response scenarios for each of the domain object resources. In each case they define the request URL, headers and body, and also identify the standard (success) response headers and body, if any.

13.1 Request succeeded, and generated a representation

For resources that return a body containing some representation.

If the response has been generated by a resource that has also modified the state (e.g. modifying a property or collection or invoking an action), then there will be no self link. This is to discourage clients from bookmarking the link.

13.1.1 Status code

  • 200 "OK"

13.1.2 Headers

  • Content-Length:

    • size of the entity body

  • Content-Type (objects):

    • application/json;profile="…​/xxx";x-ro-domain-type="yyy"

      • where xxx indicates the representation type of either "object" or "action-result" (for an action returning an object); see §A2.4.1

      • where yyy indicates the domain type identifier §A2.4.2;

        • the domain type id (if simple scheme)

        • URI of domain type (if formal scheme)

  • Content-Type (lists):

    • application/json;profile="…​/xxx";x-ro-element-type="yyy"

      • where xxx indicates the representation type of either "object-collection", "list" and "action-result" (for an action returning a list); see §A2.4.1

      • where yyy indicates the element type, §A2.4.2:

        • the domain type id (if simple scheme)

        • URI of domain type (if formal scheme)

  • Content-Type (other):

    • application/json;profile="…​/xxx "

      • where xxx indicates any other representation type, see §A2.4.1

  • Caching headers:

    • TRANSACTIONAL, see §A2.13

      • if the object is transactional

    • NON_EXPIRING, see §A2.13

      • if the implementation can determine that the returned representation is safe to cache (e.g. the returned objects are immutable reference data)

  • ETag

    • digest of timestamp

13.1.3 Body (representation)

The representation will depend on the resource being requested.

13.2 Request succeeded, and generated representation of a new object

13.2.1 Status code

  • 201 "OK"

13.2.2 Headers

  • Content-Length:

    • size of the entity body

  • Content-Type:

    • application/json;profile="…​/object";x-ro-domain-type="yyy"

      • where yyy indicates the domain type (for object representations, §A2.4.2

        • the domain type id (if simple scheme)

        • URI of domain type (if formal scheme)

  • Caching headers:

    • TRANSACTIONAL, see §A2.13

      • if the object is transactional

  • ETag

    • digest of timestamp

  • Location:

    • the URI of the resource of the object just created

13.2.3 Body (representation)

Representation of a domain object, see §C14.4.

13.3 Request succeeded, but generated no content

This response is most often generated as the result of a validation succeeding (if x-ro-validate-only is supported, §A3.2). Note, by contrast, that invoking a void action DOES return a representation §C19.4.4.

13.3.1 Status code

  • 204 "No content"

13.3.2 Headers

  • Warning (optional)

    • indicates an informational message generated by the domain object’s business logic

13.3.3 Body

  • empty

13.4 Bad request

Generated either as the result of a syntactically invalid request

13.4.1 Status code

  • 400 ("bad request")

    • missing arguments

    • arguments are malformed

13.4.2 Headers

  • Warning

    • Message text is implementation-specific, but should describe the error condition sufficiently to enable developer-level debugging

13.4.3 Body

If arguments §A2.9.2 /properties (§C14.2, §B9) are malformed, (for example, incorrect datatype), then the response body is the same as the request body, but additionally will indicate the arguments/properties that are invalid using an "invalidReason" json-property to indicate why they are invalid.

For example:

{
  "fromDate": {
    "value": "2009-13-33",
    "invalidReason": "could not be parsed as a date"
  },
  ...,
}

13.5 Not authorized (user is not authenticated)

13.5.1 Status Code

  • 401 "Forbidden"

13.5.2 Headers

  • WWW-Authenticate

    • standard authentication challenge header

13.5.3 Body

  • empty

13.6 Forbidden (user not authorized to access resource)

If the user attempts to invoke a resource that is disabled.

13.6.1 Status Code

  • 403 "Forbidden"

13.6.2 Headers

  • Warning

    • same text as "disabledReason" in object representation

13.6.3 Body

  • empty

13.7 Object or object member not found or not visible

This is the response if a requested object or object member does not exist, or if the object/member exists but is not visible based on the current user’s credentials.

13.7.1 Status Code

  • 404 "Not found"

13.7.2 Headers

  • Warning

    • No such service {serviceId}

    • No such domain object {oid}

    • No such property {propertyId}

    • No such collection {collectionId}

    • No such action {actionId}

13.7.3 Body

  • empty

13.8 Resource has invalid semantics for method called

13.8.1 Status code

  • 405 ("method not allowed")

13.8.2 Headers

  • Allow

    • comma-separated list of methods that are supported, as per RFC 2616

  • Warning

    • object is immutable (if attempt any PUT, DELETE or POST)

    • action is not side-effect free (if attempt GET Act/Invoke)

    • action is not idempotent (if attempt PUT Act/Invoke)

    • collection is not a list (if attempt POST Collection)

    • collection is not a set (if attempt PUT Collection)

    • object cannot be safely deleted (if attempt DELETE Object)

13.8.3 Body

  • empty

13.9 Not acceptable

The client has specified an Accept header that does not include a media type provided by the resource.

For resources that return "application/json" representations, a 406 response code will occur if the Accept header is set to "application/json" but has an incompatible "profile" parameter. For example, specifying a profile="…​/collection" for anything other than a collection resource §C17.1 will return a 406.

A 406 can also be returned for blob/clob property resources §C16.2.2 when there is a mismatch between the Accept header and the media type of the stored blob/clob. For example, setting Accept to "image/jpeg" for a "video/h264" will return a 406.

13.9.1 Status code

  • 406 ("not acceptable")

13.9.2 Headers

  • none

13.9.3 Body

  • empty

13.10 Precondition failed (object changed by other user)

13.10.1 Status code

  • 412 "precondition failed"

13.10.2 Headers

  • Warning

    • "Object changed by another user".

The ETag header is deliberately not returned in order to force client to re-retrieve an up-to-date representation

13.10.3 Body

  • empty

13.11 Unprocessable Entity (validation error)

Generated as the result of a validation failure.

13.11.1 Status code

  • 422 ("unprocessable entity")

    • property member values are invalid (if updating multiple properties §C14.2, or if persisting a proto-persistent object §B9.1

    • "Arguments invalid"

      • details are provided in the body

13.11.2 Headers

  • Warning

    • Message text is implementation-specific, but should describe the error condition sufficiently to enable developer-level debugging

13.11.3 Body

If arguments §A2.9.2/properties (§C14.2, §B9.1) are invalid, then the response body is the same as the request body, but additionally will indicate the arguments/properties that are invalid using an "invalidReason" json-property to indicate why they are invalid.

For example:

{
  "fromDate": {
    "value": "2009-12-01",
    "invalidReason": "The from date cannot be in the past"
  },
  ...
}

If no individual argument/property was invalid, but the set of such is invalid (e.g. fromDate > toDate), then an "x-ro-invalidReason" json-property is provided at the root of the map.

For example:

{
  "fromDate": ...,
  "toDate": ...,
  "x-ro-invalidReason": "To date cannot be before from date"
}

The json-property has the prefix "x-ro-" in this case in order to avoid clashes with the argument/property names

13.12 Precondition header missing

This represents a syntax error where a required precondition header (for example, If-Match if modifying state of a resource) was not included in the request.

13.12.1 Status code

  • 428 "precondition header missing"

13.12.2 Headers

  • Warning

    • "If-Match header required with last-known value of ETag for the resource in order to modify its state".

13.12.3 Body

  • empty

13.13 Domain logic failed, or Implementation defect

13.13.1 Status code

  • 500 ("internal server error")

13.13.2 Headers

  • Warning

    • error message raised by business logic in the domain model, or

    • exception message raised by the Restful Objects implementation itself

13.13.3 Body

  • the error representation §B10.