Apache Causeway v2 Profile (Simplified Representation)

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.

Apache Causeway also provides support for its own simplified representation for the most commonly-used representations. This is implemented using the ContentNegotiationService described in the architecture chapter.

Accept Header

The RO spec uses the standard Accept header for content negotiation, and defines its own "profile" for the standard representations; these take the form:

Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"

where "xxx" varies by resource. The detail can be found in section 2.4.1 of the RO spec.

The "Causeway" profile allows the client to request simplified representations for the most frequently accessed resources. This is done by specifying an Accept header of:

Accept: application/json;profile="urn:org.apache.causeway/v2"

Not every resource supports this header, but the most commonly accessed ones do. In each case the server will set the Content-Type header so that the client knows how to process the representation.

The screencast demonstrates the feature.

The sections below explain in a little more detail what is returned when this profile is activated.

Domain Object

If a domain object resource (section 14) is accessed with the Apache Causeway profile, the resultant representation is a JSON object with simple key/value pairs for each property.

The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced object. Each such element contains key/value pairs of each property (in other words, a grid of data is returned). Each element also has a special $$href property (so that the client can easily navigate to a resource for that object) and a $$title property (to use as a label, eg the hyperlink text).

In addition, the representation defined by the RO spec is also included, under a special $$ro property.

For example, in a todo app, accessing this resource:

http://localhost:8080/restful/objects/TODO/45

with an Accept request header of:

Accept: application/json;profile="urn:org.apache.causeway/v2"

returns the following representation:

{
  "$$href" : "http://localhost:8080/restful/objects/TODO/45",       (1)
  "$$instanceId" : "45",                                            (2)
  "$$title" : "Buy bread due by 2015-12-04",                        (3)
  "description" : "Buy bread",                                      (4)
  "category" : "Domestic",
  "subcategory" : "Shopping",
  "complete" : false,
  "atPath" : "/users/sven",
  ...
  "similarTo" : [ {                                                 (5)
    "$$href" : "http://localhost:8080/restful/objects/TODO/46",
    "$$instanceId" : "46",
    "$$title" : "Buy milk due by 2015-12-04",
    "description" : "Buy milk",
    "category" : "Domestic",
    ...
  }, {
    "$$href" : "http://localhost:8080/restful/objects/TODO/47",
    "$$instanceId" : "47",
    "$$title" : "Buy stamps due by 2015-12-04",
    "description" : "Buy stamps",
    "category" : "Domestic",
    ...
  },
     ...
  } ],
  "dependencies" : [ ],
  "$$ro" : {                                                        (6)
    "links" : [ ... ],
    "extensions" : { /* ... */ },
    "title" : "Buy bread due by 2015-12-04",
    "domainType" : "TODO",
    "instanceId" : "45",
    "members" : { /* ... */ }
  }
}

1	hyperlink to the representation
2	instance id of the domain object (unique within its type)
3	title of the domain object
4	all the properties of the domain object (to which the caller has access), as key/value pairs
5	contents of each collection
6	special `$$ro` json-prop, being the normal RO Spec representation for this object

with a Content-Type header:

Content-Type: application/json;
              profile="urn:org.apache.causeway/v2";repr-type="object"

Domain Object Collection

If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as an array of elements of key/value for each referenced object, and again each element the containing the key/value pairs of the properties of that object (a grid, again).

In addition, the representation defined by the RO spec is also included, as a special object with a single $$ro property.

For example, in a todo app, accessing this resource:

http://localhost:8080/restful/objects/TODO/45/collections/similarTo

with an Accept request header of:

Accept: application/json;profile="urn:org.apache.causeway/v2"

returns the following representation:

[                                                                   (1)
{
  "$$href" : "http://localhost:8080/restful/objects/TODO/46",       (2)
  "$$instanceId" : "46",                                            (3)
  "$$title" : "Buy milk due by 2015-12-04",                         (4)
  "description" : "Buy milk",                                       (5)
  "category" : "Domestic",
  ...
}, {
  "$$href" : "http://localhost:8080/restful/objects/TODO/47",
  "$$title" : "Buy stamps due by 2015-12-04",
  "description" : "Buy stamps",
  "category" : "Domestic",
  ...
}, {
  "$$href" : "http://localhost:8080/restful/objects/TODO/48",
  "$$title" : "Mow lawn due by 2015-12-10",
  "description" : "Mow lawn",
  "category" : "Domestic",
  ...
},
...
, {
  "$$ro" : {                                                        (6)
    "id" : "similarTo",
    "memberType" : "collection",
    "links" : [ ... ],
    "extensions" : { /* ... */ },
    "value" : [ ... ]
  }
}
]

1	returns a JSON array, not a JSON object
2	hyperlink to the representation
3	instance id of the domain object (unique within its type)
4	title of the domain object
5	all the properties of the domain object (to which the caller has access), as key/value pairs
6	last element is a special object with a single `$$ro` json-prop, being the normal RO Spec representation for this object

with a Content-Type header:

Content-Type: application/json;profile="urn:org.apache.causeway/v2";repr-type="object-collection"

Action Invocation

When an action is invoked (section 19) it can return a domain object, a list, a scalar, or return nothing.

Returning an Object

If the action returned an object, then the domain object representation is returned.

For example, in a todo app, accessing this resource:

http://localhost:8080/restful/objects/TODO/45/actions/updateCost/invoke

with an Accept request header of:

Accept: application/json;profile="urn:org.apache.causeway/v2"

returns the following representation:

{
  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
  "$$instanceId" : "45",
  "$$title" : "Buy bread due by 2015-12-04",
  "description" : "Buy bread",
  "category" : "Domestic",
  "subcategory" : "Shopping",
  "complete" : false,
  ...
  "similarTo" : [ ... ]
  ...
  "$$ro" : { /* ... */ }
}

with a Content-Type of:

Content-Type: application/json;profile="urn:org.apache.causeway/v2";repr-type="object"

... in other words no different to a representation obtained of the returned domain object directly.

Returning a List

On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned. This is very similar to that returned by a (parented) object collection, though with a slightly different Content-Type to distinguish.

For example, in a todo app, accessing this resource:

http://localhost:8080/restful/services/ToDoItems/actions/notYetComplete/invoke

with an Accept request header of:

Accept: application/json;profile="urn:org.apache.causeway/v2"

returns the following representation:

[ {
  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
  "$$instanceId" : "45",
  "$$title" : "Buy bread due by 2015-12-04",
  "description" : "Buy bread",
  "category" : "Domestic",
  ...
}, {
  "$$href" : "http://localhost:8080/restful/objects/TODO/46",
  "$$instanceId" : "46",
  "$$title" : "Buy milk due by 2015-12-04",
  "description" : "Buy milk",
  "category" : "Domestic",
  ...
},
...
, {
  "$$ro" : {
    "links" : [ ... ]
    "resulttype" : "list",
    "result" : { /* ... */ }
      "value" : [ ... ],
      "links" : [ ... ],
      "extensions" : { }
    }
  }
} ]

with a Content-Type header:

Content-Type: application/json;profile="urn:org.apache.causeway/v2";repr-type="list"

Returning Scalar/Nothing

Note that actions returning scalar values or nothing (which includes void actions) are not supported; for these the regular RO spec representation will be returned.

Global Config Props (Deprecated)

If all that is required is a very simple representations (of objects), you can configure the Restful Objects viewer to provide a simplified output, then this can be done with a number of (global) configuration properties.

These configuration properties pre-date the support for the Apache Causeway profile, and are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request basis (as is the case with the Accept header used for the Apache Causeway profile). They have therefore been deprecated, and may be removed in the future.

Details can be found in here.