RO Specification

The Restful Objects v1.0 specification defines a comprehensive hypermedia API, consisting of HTTP resources and corresponding JSON representations, for accessing and manipulating a domain object model.

The Restful Objects spec is available online at https://restfulobjects.org.

Goals of the Spec

The goal of Restful Objects is to allow domain models to be accessed through HTTP resources, returning a set of JSON representations. These representations can then be consumed by any client (e.g. JavaScript, Java, .NET, Ruby, Python).

Both the resources and representations are generalized so that they can be applied to any domain model, and by default all representations have media types designed to allow a completely generic client to be written, capable of working, unmodified, with any domain model that has a Restful Objects interface.

Alternatively, the developer may write a custom client that has some shared knowledge of the domain being exposed, and render the information in a more specific fashion.

Restful Objects also defines that representations are served up with parameterized media types. This allows clients to use content negotiation to ensure that representations do not change in a breaking fashion, enabling server and client to evolve independently.

The Restful Objects specification is at a higher-level of abstraction than, say, the JAX-RS specifications for Java platform, or the WCF specifications on .NET. Specifically, the domain classes that it exposes are represented in a very general form. They consist of:

  • properties (fields), each holding either a scalar value or reference to another object;

  • collections, each holding a vector reference to other entities;

  • actions (operations/methods), whereby the object can execute business logic.

Beyond this, though, Restful Objects makes very few assumptions. In particular, Restful Objects does not prescribe the nature of the domain model.

The Restful Objects spec may be downloaded directly from github as either a PDF or as a Word doc.

Resources and Representations

The diagram below - taken from the Restful Objects spec - shows the various resources (URLs) and representations (JSON) that are defined:

ro spec resources and representations

The resource URLs are always well-defined, but Apache Causeway' implementation allows for different representations to be returned, using content negotiation. This is discussed further below.

Apache Causeway' implementation

The Restful Objects viewer is Apache Causeway' implementation of the Restful Objects spec. It implements all the mandatory features of the specification. It also implements some of the optional capabilities (as defined in section 3 of the RO spec, and as represented in the version resource, section 8.1):

Capability Support Notes

blobsClobs

yes

deleteObjects

yes

domainModel

formal

The 'simple' scheme is not supported

validateOnly

yes

protoPersistentObjects

yes

Extensions

The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but described in chapter 34, "ideas for future extensions".

Content Negotiation

Apache Causeway provides two levels of support for content negotiation (section 34.1)

x-ro-domain-type

The first level is very similar to the "Domain Model Agnostic" approach sketched out in the RO spec. The client can send an x-ro-domain-type parameter for either domain object representations (section 14 of the spec) or action invocation results (section 19). This can be combined with either application/json or application/xml.

For example, the client could use an Accept header such as:

Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerViewModel"

The server will use the ContentMappingService to attempt to transform the domain object into the requested x-ro-domain-type. The whole process is discussed in more detail in the architecture chapter.

Apache Causeway profile

The representations defined by the RO spec are very rich and enable complex client-side applications to be built. However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations. Examples of such tools are Angular Bootstrap, Angular XEditable, Angular Strap.

This support is discussed further in the simplified representations chapter.

Minimizing Round-trips

The Restful Objects viewer supports the x-ro-follow-links query parameter in a way very similar to that suggested in the RO spec (section 34.4), the main point being to avoid the "N+1" problem of too many (slow) network calls. For example, using this feature one can load a grid of data in a single call. (That said, the Apache Causeway v2 simplified representation supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).

For example, with an app containing three entities, Grandparent, Parent and ChildJdo that define a hierarchy of 1:m relationships, we could define the following queries:

  • show parent and its children (titles)

    http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value

  • show parent and its children (full details)

    http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value.href

  • child’s parent (title)

    http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value

  • child’s siblings (up to its parent, down to children)

    http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value.members[children].value

Honor UI hints

By default the representations generated by Restful Objects ignore any Apache Causeway metamodel hints referring to the UI. In particular, if a collection is annotated then Render(EAGERLY) then the contents of the collection are not eagerly embedded in the object representation.

However, this behaviour can be overridden globally using the causeway.viewer.restfulobjects.honor-ui-hints configuration property:

This means that standard Apache Causeway annotations can be used as a simple way to obtain follow-links (driven from the server model, though, rather than the requesting client).