= RO Specification

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


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 link:https://restfulobjects.org[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:

image::restfulobjects/ro-spec-resources-and-representations.png[width="800px"]

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


== Apache Isis' implementation

The Restful Objects viewer is Apache Isis' 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 link:https://www.restfulobjects.org/spec/1.0/section-a/chapter-03.html[section 3] of the RO spec, and as represented in the version resource, section 8.1):

[cols="1a,1a,1a",options="header"]
|===

| 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 link:http://www.restfulobjects.org/spec/1.0/section-e/chapter-34.html[chapter 34], "ideas for future extensions".

=== Content Negotiation

Apache Isis provides two levels of support for content negotiation (section link:http://www.restfulobjects.org/spec/1.0/section-e/chapter-34.html#34.1-content-negotiation[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 (link:http://www.restfulobjects.org/spec/1.0/section-c/chapter-14.html[section 14] of the spec) or action invocation results (link:http://www.restfulobjects.org/spec/1.0/section-c/chapter-19.html[section 19]).
This can be combined with either `application/json` or
`application/xml`.

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

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

The server will use the xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[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 xref:vro:ROOT:content-negotiation.adoc[architecture] chapter.

==== Apache Isis 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
link:http://angular-ui.github.io/bootstrap/[Angular Bootstrap],
link:http://vitalets.github.io/angular-xeditable/[Angular XEditable],
link:https://github.com/mgcrea/angular-strap[Angular Strap].

This support is discussed further in the xref:vro:ROOT:content-negotiation/apache-isis-v2-profile.adoc[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 link:https://www.restfulobjects.org/spec/1.0/section-e/chapter-34.html#34.4-minimizing-round-trips-(x-ro-follow-links)[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 xref:vro:ROOT:content-negotiation/apache-isis-v2-profile.adoc[Apache Isis 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)
+
pass:[<pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children\].value]

* show parent and its children (full details)
+
pass:[<pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children\].value.href]

* child's parent (title) +
+
pass:[<pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent\].value]

* child's siblings (up to its parent, down to children) +
+
pass:[<pre>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 Isis 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
xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.honor-ui-hints[isis.viewer.restfulobjects.honor-ui-hints] configuration property:

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