This section summarises the standard json-properties, headers and status codes that are understood by Restful Objects implementations.

4.1 Specified json-properties

There are a number of json-properties specified by Restful Objects that have well-defined and fixed meanings, irrespective of which representation they appear within. They are:

JSON-Property Description


Provides the reason (or the literal "disabled") why an object property or collection is un-modifiable, or, in the case of an action, unusable (and hence no links to mutate that member’s state, or invoke the action, are provided).


Provides the reason (or the literal "invalid’) why a proposed value for a property, collection or action argument is invalid. Appears within an argument representation §A2.9 returned as a response.


Provides the reason why a SET OF proposed values for properties or arguments is invalid. The "x-ro-" prefix is to avoid name clashes with the property/argument names.


A list of additional links from the representation to other resources. Implementation-specific links may also be present in this list; see §A2.11.


Map of additional information about the resource. Implementation-specific json-properties may also be present in this map; see §A2.11.

4.2 Specified (reserved) query parameters

The query parameters reserved by Restful Objects are:

Header Description


Which domain model scheme §A3.1 the server should return. Understood only by servers that provide "selectable" for the "domainModel" capability §B8


Indicates that parameters should be validated but no change in state should occur.

4.3 Specified headers

Restful Objects defines both request and response headers.

4.3.1 Request headers

The request headers specified by Restful Objects are:

Header Description


The list of media types accepted by the client.


The value of the ETag response header for the most recently obtained representation of a resource.

4.3.2 Response headers

The response headers specified by Restful Objects are:

Header Description


The HTTP methods that are supported by the resource. Returned only in conjunction with a 406 ("Not allowed")


Whether the representation may be cached or not. Representations of resources representing domain objects will typically disable caching, but some representations (for example, of immutable objects, or of domain types) may be cached.


The last modified timestamp of a persistent resource. The value of this should be passed as the If-Unmodified-Since header.


Header to describe either any errors returned by the server implementation, or, as raised by the domain object business logic (e.g. if the request was syntactically valid but could not be completed).


Depends upon representation; in the form "application/json;profile=http:// restfulobjects.org/xxx ".

4.4 Specified status return codes

The status return codes specified by Restful Objects are:

Code Description When



Successfully generated representation


No content

Request was successful but generated no representation; or validation (x-ro-validate-only) succeeded. Note however that invoking a void action DOES return a representation §C19.4.


Bad request

Represents any of: a syntactically invalid request, missing mandatory information (e.g. If-Unmodified-Since header), or a warning message generated by the application.


Not authorized

Problem wih user’s credentials (ie user is not authenticated).



User is not authorized to invoke resource (modify property or collection, or invoke action)


Not found

Property, collection or action not found (could be that the member is hidden for the requesting user)


Method not allowed

An attempt was made to invoke a resource with an HTTP method that is not supported by that resource.


Not acceptable

Content type of the representation that would be returned is incompatible with the provided Accept header (in other words, the server is unable to comply with the accept instruction).


Precondition failed

Concurrency error; the object' has been modified and its current etag does not match that provided in the If-Match header.


Internal server error

Indicates that the domain object threw an exception in its business logic


Not implemented

This implementation of Restful Objects does not support the feature requested.

All client- and server-side errors (4xx and 5xx) will also result in a Warning header being returned to describe the nature of the problem. The format of this Warning should be [1]:

109 RestfulObjects xxx


  • 199 indicates a miscellaneous "warn-code" (as per HTTP/1.1 spec)

  • RestfulObjects is the "warn-agent"

  • xxx is the text of the message generated by the implementation

In some cases the implementation will be able to provide a detailed error message; otherwise it should return a standard generic message. The sections describing resource responses detail these messages.