Restful Objects Specification

The Restful Objects specification defines a set of RESTful resources, and corresponding JSON representations, for accessing and manipulating a domain object model. The current version of the spec is v1.0.0. (The spec may be downloaded via the Downloads tab).

Resources and Representations

The spec defines a uniform interface to the domain objects. This uniformity is expressed in terms of the format of URLs, use of standard HTTP methods, standard and custom HTTP headers, standard HTTP return codes, use of JSON representations, the concept of a representation type to allow the dynamic handling by clients, standard attributes within JSON representations, and standard representation of links between representations.

The Restful Objects spec 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 objects that it exposes as resources are thought of in similar terms to UML, in that they consist of properties (holding either a scalar value or reference), collections (holding a vector of references), and actions (whereby the object can execute business logic).

Restful Objects is agnostic as to the nature of the server-side state that it exposes, in that it may be used either to expose domain entities (Customer, Order, Product) or may be used to expose use cases/commands (CheckIntoFlight, CancelOrder).

Finally, the spec is designed to support clients that use HATEOAS (hypertext as the engine of application state, with opaque URI values) and also those that prefer to use templated URIs.


Even though v1.0.0 of the Restful Objects spec has now been issued, we intend to continue working on the spec, clarifying it, enhancing it, and adopting new and emerging standards where appropriate. As such, we always welcome your feedback, either via the issue tracker on github, or just by commenting here.

If you want to reference the spec on Twitter, please use the #restfulobjects hashtag.


The spec is published under Creative Commons 3.0 Attribution-ShareAlike.

5 thoughts on “Restful Objects Specification

  1. I just finished reading v1.0.0, and I would like to say great job. Regarding the future extensions, I vote for : content negotiation, sorting, pagination. I consider these a must have for any REST API. I have been looking for a REST API design spec that incorporates HATEOAS. I have also looked at HAL and JSON Hyper-Schema, but Restful Objects seems to be the most well thought out in terms lending itself to building a generic framework … the below quote from the spec is a powerful goal:

    “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..”

    I plan to implement a Restful Objects framework in Groovy / Java – I’ll keep you posted.

    By the way, I see that v1.1.0 is available on GitHub, however there is no “official” mention of its release. Is that intentional ?

    • Thanks for the feedback, glad that RO appeals. Future versions of the RO spec might well be refactored to incorporate other aspects of other specs such as HAL, eg for link representations, but as you note, RO’s goals are broader.

      I haven’t “officially” announced RO v1.1.0 only because I still need to properly proof read it. But basically that version is “feature complete”.

      As to you writing a new framework implementing the spec – that’s great news! You mention Groovy … I was thinking myself that Grails would make a good platform for doing so. Yes, do let me know how you get on.


      PS: I notice a bunch of tickets raised on the github website… are they from you? If so, thanks for that, will attend to them.

    • Let me distinguish between the spec and implementations.

      With respect to the spec, it has admittedly been a while since v1.0.0 was released, but I’ll be releasing v1.1.0 just as soon as I’ve proof read it. And v1.2.0 is likely to follow along rather sooner … we want to bring the table grid support (section 34.9) into the spec proper.

      With respect to implementations, on the .NET side (RestfulObjects for .NET, hosted at has had a number of releases this year (2013), and they are just finishing up the v1.1.0 support. On the Java side, Apache Isis’ implementation is still at v1.0.0, but we had plan to make RO part and integral part of the next-generation of Isis’ viewers, likely using AngularJS. And in fact, the Naked Objects on .NET is following a very similar route, through their Spiro project.

      My view is that RO is unlikely ever to be used as the basis for bespoke Rest implementations – the API it defines is probably too rich/sophisticated to be practicable to code by hand. However, RO is very important for generic frameworks, specifically the naked objects implementations… indeed, RO is the natural development/evolution of the NO paradigm. For the moment NO itself remains a very niche pattern, but we think that RO has a good chance of bringing it into the mainstream.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s