Introducing: Restful Objects

Restfull objects as I understood it from your article are Entity services through a REST API. It brings the added value of REST on those entities exposed via Entity Services. Well I might be a bit extreme here but I found the entity services to be a sort of anti pattern and should be avoided :( Rest is meant to access resources not objects. Objects are composed of state and operations. What I see here is RESTfull DTO and RESTfull functions not RESTfull objects. This of course only translate what I think of it. I haven't found a proper way to have my domain object be access as resources. Imagine this. I get my domain object through an open API. I manipulate my domain entity in any device that can access all the required resources needed for this manipulation and then send back my resource back to the master. Sounds great for me but It will bring a lot of issues like concurency, race condition... Anyway it is an interesting article but not sure if the concept is applicable.

I'm not sure I fully understand your point. The 'Domain Object Representation' returned by the domain object resource contains both its properties and also all of the actions that that user can invoke on that object - in the form of links to action resources on the server - which may be to instance methods on that object in the server, or to services that provide methods for that object. In that sense I think it is as object-oriented as it is possible to be on REST. I recommend that you take a quick look at the RO specification itself for further clarification.

I don't think this technology will work for everybody, but for internal Line of Business Apps, it sounds promising. The metaphor of Odata++ is great.

To your point about concurrency etc... the standard HTTP approach for this is to use If-Match and ETags headers, returning a 412 status code if the resource has changed in the meantime. The RO spec defines the same usage; see section 2.15.

~/objects/customers/31/actions/lastOrder/invoke.. isn't this RPC?

No, that's a URL. Depending on the semantics of the action, it can be invoked either with a GET if query-only (19.1 of the spec), a PUT if idempotent (19.2), or a POST if neither (19.3). Contrast this with SOAP (which I do agree is an RPC) where everything is a POST.

Moreover, the way that you get to that URL is by following links, with the appropriate "rel" attribute (2.7 of the spec). In this way the spec defines a fully HATEOAS API.

Sorry my bad.. I was under the impression that the URIs should reference nouns not verbs.

For REST, a URI should reference a resource. The statement above that resources are mapped to domain objects is misleading at best. It's more that every aspect of a domain model appears to be mapped as a resource. In other words, your domain model is blown apart and every piece made into a resource. I'm not you can really differentiate that from RPC, though, as I wouldn't agree that those pieces are resources. Also, given the encapsulation property of OO, I don't think there's any way to map to REST directly. OO hides state, REST exposes state. They are the antithesis of one another.

RO only exposes properties that are public - it does not expose private state. Whether/which properties of an object should be public - as distinct from hidden by actions - is down to the design of the model. RO doesn't care. You could hide all state and expose only actions - the resource/representation model is still fine.

For anyone interested: I have been working on another open source client for Restful Objects called Spiro. It takes the form of a single-page app and is written using backbone.js, underscore.js, and jsrender for templates.

Spiro will function as a generic client for any domain object model with a Restful Objects 1.0 API. The models (spiro-models.js) can also be used as the basis for building a completely custom UI - using standard backbone.js patterns.

This is a work in progress - it is far from complete - but the parts that are implemented work quite well. You can find the code and more details here: restfulobjects.codeplex.com/wikipage?title=Spir...

(If you are on the .NET platform, you can also install it as a ‘pre-release’ NuGet package: nuget.org/packages/RestfulObjects.Spiro/0.2.0-beta

Per the doubt you express about which pieces of a domain object model can be resources and which not: "any information that can be named can be a resource" (Fielding).

By that definition there's nothing wrong with the spec defining "the first name of a customer" as a resource, nor "the contents of a basket", nor, indeed "add to basket".

I think this view highlights a distinction in our views/definitions of "domain model". My domain models are primarily behavioral, thus exposing one of my domain models would, in fact, be akin to exposing an RPC service. If my model is just like a DTO, then sure, this could work for some people. I've never found that my domain maps very well, and I certainly wouldn't want to automate that process. My domain should be a good domain model. How I expose that domain may differ depending on the delivery mechanism, e.g. web, console, tests, etc.

We'll have to disagree. I wouldn't say "add to basket" is a "name." Also, while "first name of a customer" is a "name," I don't think I'd ever expose that as a resource. That greatly depends on what I'm trying to do. It's really just my opinion that I don't see automated mappings as providing a good design from an OO model. I applaud your effort to try, but I like finer control over the meaning of my resources. My exposed web api is just not the same as the underlying domain model, even though they are related.

Appreciate this discussion, and you do raise a valid point in your last sentence: in some scenarios, the web api that one wishes to expose is not the underlying domain model.

As we discuss briefly in the article and the spec discusses in more depth (section 29, 33.3, 33.4, 33.5), there will be cases (internet, bespoke clients) when what should be exposed is a resource model that mediates to but does not expose an underlying domain object model. This is much closer to the style advocated by Oberg and Webber.

Even here, though, RO offers benefit: you can develop your resource models as pojos/pocos, which mediates to/from the underlying domain model. This resource model can be tested outside of a big web stack, and you save yourself having to ever go down to the lower level of abstraction (of JSON, HTTP headers etc etc). And, the REST API you get is going to be much more uniform than if you coded it up yourself.

The Restful Objects spec was one of the drivers in choosing a platform to build our next generation business applications. Having the same pattern and API implemented on both Java and .NET enables us to deliver applications within our customer's platform constraints (we eventually chose Apache Isis as our primary framework). We're also glad to see some interesting projects starting up to create appealing viewers for the RESTful API. And another huge advantage we're getting from having a complete RESTful API is in migrating and exchanging data from (legacy) systems to the new Apache Isis applications.

Just to add my two cents...

The javascript frontend I'm working on needs to know one uri: the homepage resource. From there I can operate solely on rels and the defined media types[1].

So to take the table under the Links section (read .../services as urn:org.restfulobject:rels/services):

var ro = new RO.Client("/");
var services = ro.findLinkByRel(".../services").follow(); // follow() figures out the correct HTTP method
displayAsMenu(services);

var result = anAction.findLinkByRel(".../invoke").follow(args);

displayAsDomainObject(result);

I have one more question. Re "any information that can be named can be a resource" - what information is being named by "add to basket"? If I understand correctly "add to basket" is an action. Is this really some information, a nameable resource? Sorry for asking seemingly stupid questions but your explanation seems to contradict some other articles on REST so I'm trying to make sense of it all. POST-ing data to a resource that represents a collection of items or a basket makes sense to me but I'm struggling to understand how these "domain actions" are RESTful. Thanks.

Lots of RESTful APIs try to map a domain object model in terms of CRUD operations: boiling things down to posting to collections, or updating/deleting existing resources. In RO terms, that would correspond to just manipulating state using the domain object property and collection resources.

At the other extreme, there is advice to map everything in terms of state transitions of resource models (eg Webber's Restbucks article here on InfoQ). Nothing wrong with that for a public web api. The resources that represent these state transitions are much more akin to domain actions.

RO aims to support both of these approaches, to make it easy to expose either your domain objects, or domain services that act as a resource model in front of a hidden domain model. Either domain objects or services can expose arbitrary business logic through their actions, and these actions can have arbitrary pre- and post-conditions.

Thanks for that, Adam. I've seen a few commentators on twitter look at the table in the article and surmise that RO is just a bunch of templated URLs. Thanks for dispelling that and demonstrating a little more completely how RO supports HATEOAS in your JS client.

This is clearly what I meant. The operation will not be executed on your object. It will be executed on the object on the server. That object might have changed since the last time you got it. Imagine this I get my object. Somenoe else also does. He change it or delete it. On what my operation will be executed? I do not have a RESTfull object. You a view on the state of the object and a link to an operation. You do not have an object as resource. Hope this will be more clear.

Richard, Dan congrats. I found the approach very valuable in order to provide standardized way of exposing an domain object model in a technology independent way.

The capability of consume data and use a generic client to render the UI is also a great feature, useful for some kinds of applications.

I have been working several years with object models and code generation to create server components and client ones. I have been exploring Web Services, REST, OData and different as ways of communicating service consumer with service producers. See InfoQ Multichannel UserInterfaces.

So, definitely, I am going to explore the applicability of Restful Objects to our domain. I see a great potential in Restful Objects for simplifying integration between systems, in the way it standardizes many aspects.

I have some questions about using RO in production systems:

• 1. How authentication is handled in/(hooked with) RO? Standard HTTP/S authentication?


• 2. When retrieving an object, all properties are returned always? Is there any mechanism available to limit or customize the amount of data (properties to be retrieved)? Different cases of use will have different information needs (aka DTO)


• 3. Is there a way to retrieve a direct object subgraph (sample: Invoice, Customer, Invoice Lines and related Products) (in order to avoid 1+N calls over the wire)?


• 4. When retrieving let’s say “Country.Customers” is there any protection like a paging scheme to protect us from directly getting 1 million of objects and therefore degrade the performance of the system?


• 5. There are plans for advanced/dynamic queries over collection of objects? E.g: return the customers in Spain that have bought a given product X in the last 3 years.

So this is just concurrency - which is an issue for virtually all client-server systems. As Dan says Restful Objects uses standard http mechanisms to handle this (2.15 in the spec). The effect of this is that if the object has been changed on the server since you retrieved it your operation will fail with a 412 'precondition failed' prompting you to get a fresh representation.

Thanks, Pedro.

"1. How authentication is handled in/(hooked with) RO? Standard HTTP/S authentication?"

The RO spec does not mandate/assume any particular flavour of authentication - you can use whatever you would for any RESTful API.

"2. When retrieving an object, all properties are returned always? Is there any mechanism available to limit or customize the amount of data (properties to be retrieved)? Different cases of use will have different information needs (aka DTO)"

The domain object representation returns all properties that the given user is authorized to see. If you want to limit what is actually returned then you can simply return a 'view model', specific to that context. There is quite a bit on this within the spec. That said, though View Models can certainly be useful, the need for them is commonly overstated. Provided you can be sure that the representation only returns data that the user is authorized to see (which is the case) then in many cases, it may be much simpler just to customize which properties are actually displayed in the client.

"3. Is there a way to retrieve a direct object subgraph (sample: Invoice, Customer, Invoice Lines and related Products) (in order to avoid 1+N calls over the wire)?"

The Restful Objects 1.0 spec does not explicitly provide for eager loading, but there is a substantial discussion of the recognised need for this at the back of the spec, and it will almost certainly be added in v1.1.

"4. When retrieving let’s say “Country.Customers” is there any protection like a paging scheme to protect us from directly getting 1 million of objects and therefore degrade the performance of the system?"

For the Restful Objects for .NET implementation, there is now such a guard. The default is 20, but you can override this globally. Right now if you want paging, you need to write actions that support it. But, again, it is likely that the next version of the RO spec will support paging explicitly - there is again a sketch of this in the last section of the spec.

"5. There are plans for advanced/dynamic queries over collection of objects? E.g: return the customers in Spain that have bought a given product X in the last 3 years."

Again, a likely future extension to the spec. You can certainly do such queries in the RO.NET implementation (using dynamic LINQ) - but it's not yet defined at spec level.

This is clearly the behavior you will have on an Entity services and unfortunately the same flaws. I'm not sure I will put my domain object accessible through an entity service or a RESTfull "object" API. I would put my commands and my views/projections available over a RESTFull API. Not My domain objects. but again this is only my opinion and I can understand that maybe for some simple business line application why not. Anyway thanks a lot for sharing this with us and keep being productive :)

The earlier discussion (between Dan, Ryan & Mark) nicely illustrates, I think, the 2x2 table in the article.

Ryan makes the point that for the domain models he designs would not be suitable to be exposed as a Restful API - he wants a custom-defined Restful API - and so the value of Restful Objects is much lower. I think it would be fair to say that Ryan is describing is in the bottom-right hand corner of the 2x2 in the article - a potentially public-facing API where you don't have control of the client.

Dan makes the point that Restful Objects still works for this, and still adds value, even though that value might is not as great as in the other three. We know from personal experience that even with a 'dream team' of REST-heads and the best current tooling - writing custom RESTful APIs is extraordinarily labour intensive.

But what does concern me is that so many RESTful practitioners seem unable to imagine the other three spaces on that 2x2. There is huge potential out there for REST - much more than the narrow concept of REST that most practitioners advocate right now. But the reality is that it would be almost impossible to work in those spaces without something broadly like the Restful Objects spec and frameworks that implement it automatically.

Pedro (in another thread) has picked up on this. Organisations that do have good domain models (and, admitedly, that's not all that common) now have the potential to make those models accessible *within the intranet* via a RESTful API - both to facilitate integration between disparate systems, and to facilitate development of new clients. We know large organisations interested in RO on both counts. The point is that they could never consider doing this using a custom RESTful API - there would simply be too much effort involved in defining it, implementing it, and testing it.

Dan &/or Richard,

Congratulations on the new API, it is great news to see the NO continuously adapting new features.

Can you indicate scenarios where you believe the Restful Objects API would be useful? If I have to develop an intranet solution, I can currently use the NO MVC, I can see the benefit of using the Restful Objects, for example, in system integration cases or if I had to develop a desktop client for example; that is, solutions that we normally use WCF services and DTOs; but, are there any other obvious scenarios besides those ones?

HI Enrique, I have a few.

You mentioned system integration from a desktop client, which I'd see that more as two parts of the same app (with the client app being either bespoke or generic as fits). In domain-driven design (DDD) terms, that's one bounded context. But there's also system integration across bounded contexts. For example, one government department could invoke an RO API exposed by another government department. This would be a case where accessing the API through a resource model (bottom left of the 2x2) would be advisable.

Another obvious case is using the RO API to support multiple client apps, eg a desktop app, a mobile app, etc. Here we are back into one bounded context (both the clients and server are owned by one team), and so could expose the underlying domain model directly.

A slightly less obvious case is in migrating data; as Jeroen (above) mentioned, we're taking advantage of the RO API to start trial migrations of data from an existing system into a new Isis-based system. The RO API itself is throw-away, but the point is that it delegates to the main domain logic that we're building out. There's a bunch of benefits: the users get to validate the new system using data that is familiar to them, we get to validate our business logic, and we also get some stress testing for free.

One final use case is in supporting phased migration from an existing system to a new system, which might take a number of years. We can wrap the existing system in an RO API, and put an RO API around the new system also. Clients written to the RO API can then access either the old system or new; 301 redirects can be used to hide the fact as to where the business logic invoked is being accessed from: existing system or new.

Enrique

Here's a couple of application scenarios that I'm personally interested in - but I'm hoping others might contribute more:

1. As a lingua-franca for integration between multiple systems within an intranet. Great thing is these can be on different technology platforms and with different concepts of a domain model: one might be strongly object-oriented, one might be strongly service-oriented, and one might be little more than a wrapper onto a database.

2. As a way to facilitate the development of new single-page apps for a single server. I'm astonished at how easy this is now proving to be once you have a comprehensive Restful API that delivers a consistent (small) set of JSON representations. Stef's work on the Spiro viewer (see earlier posting) shows this: he has a small set of backbone.js model objects that correspond to the RO representations, and that can form the basis of either a generic client or a bespoke client.

3. Combination of 1&2. Dan proposed a very interesting pattern for this, described in the spec, and we have spiked it.

4. Your own point about building desktop clients. I know of one organisation looking to use RO as the basis for communications between its WPF rich client and the server.

Let's here some other ideas ...

Great article, and great to see RO maturing.

>4. Your own point about building desktop clients. I know of one organisation looking to use RO as the basis for communications between its WPF rich client and the server.
Perhaps there is another also, but I think we are the client that Richard is referring to. :)

We are in the early phases of building a complex enterprise system that will consist of many different projects. The core of this system is built on Naked Objects MVC. We have a WPF desktop application that forms part of the same domain. We are going to do a spike to let this application work with the same core domain exposed via RO and auto generated C# proxies, although the WPF UI will be bespoke, not generic. I'll report back when we have actually tried this.

We will also use RO to expose an API for our business partners to integrate with us.

So far we have found NO MVC extremely beneficial and I think the extra power and flexibility that RO for .Net will add to the toolbox is very exciting.

Thanks for the pioneering work!

As you said earlier, it is true that URI's point to resources and resources should refer to nouns or "things".

So, .../customers/31 is a thing, a .../repr-types/object. And .../customers/31/actions/lastOrder is a thing, a .../repr-types/action.

An action like lastOrder, or addToBasket, has a representation with information like it's returntype and required parameters. It can also tell us where to go when we want to know the result of invoking the action, which will be a noun, as well as which HTTP method is appropriate. In that case we follow the .../rels/invoke link. I wonder if changing the name of the rel to something more noun-like, .../rels/invocation or .../rels/action-result, would make it clearer of the difference between action metadata (.../repr-types/action) and the value of the invoked action (.../repr-types/action-result). I wasn't involved in the development of the spec but came to it recently and the community has been very receptive to input about changes and future needs to support client side applications. So maybe this is something that can be discussed more.

In the case of the other member types an object has: value properties, like a customer's name, reference properties, like a customer's billing address, or collections, like a customer's payment methods, they are all public getter methods on the domain object and getters share the semantics of being side-effect free and taking zero arguments. This means we know we can access their return value through a GET. It also means that in some cases we can even safely inline the value into the domain object representation. The RestfulObjects spec currently only defines this inlining for the simple value properties, but has a proposal (section 34.4) for extending the spec to allow inlining of references and collections, on demand.

The reality is that all of this data is the result of invoking methods. The customer representation having a "name" property means there was a public getName method and the value is the result of invoking that method. The extra step that RestfulObjects took was to figure out how we can reason about accessing the result of any public method on an object, not just those with getter semantics. If other APIs do handle this they almost always hard-code the HTTP method to POST, which violates [1].

[1] www.w3.org/DesignIssues/Axioms.html

*I don't know if this is a coffee reality today but the example is good I think.*

Suppose you walk into your favorite coffee shop and the line is long. You pull out your smartphone and go to the coffee shop's app, you tap the order button. You're then asked to choose what drink you want from a menu, then what extras you want in it, what size. You confirm your order, your credit card is charged, and in a few minutes your name is called out and you pick up your drink. The process you went through to order was very scripted: step 1, 2, 3, confirm.

Now suppose you're not sure what you want to drink, so you wait in line. When you get to the register you ask: what has more calories, a shot of caramel or a shot of chocolate? The employee doesn't know but they can look it up on their computer. Caramel has 250, chocolate has 200. Yikes. Now you ask, what extras do you have that are under 100 calories? Back to the computer. Cinammon and fat-free milk. Ok, I'll have a fat-free latte with extra cinammon. I have $1.27 on this gift card. Put the rest on my credit card.

The first scenario is a highly-scripted interaction that wants to guide the customer into placing their order as quickly as possible. This is a place where exposing a separate resource model is essential. The client may not be under your control and they don't fully understand your domain.

POST .../MobileOrder
{
"DrinkName":"Mocha Frappacino",
"ExtraName":"Caramel",
"SizeName":"Venti",
"CustomerName":"Bill"
}

The second scenario, however, requires the cashier to navigate around the domain of coffee ordering to answer the customer's questions and charge their credit card correctly. Having access to the full glory of the domain model allows the cashier, who understands the domain, to navigate directly to the answer. The coffee shop will probably build both the client and server and they will evolve together.

GET .../extras/FindByName/invoke?Name=Caramel
{
"Name":"Caramel",
"Calories":250
}
GET .../extras/FindByName/invoke?Name=Chocolate
{
"Name":"Chocolate",
"Calories":200
}
GET .../extras/FindByMaxCalories/invoke?Calories=100
{
"elements": [
{
"Name":"Fat-free milk",
"Calories":25
},
{
"Name":"Cinammon",
"Calories":10
}
]
}

I left out all of the hypermedia to make the above easier to read.

I agree, Adam, that e.g. '../rels/..-invocation' might have been better than '../rels/..-invoke' in that it might have caused fewer people to get the wrong idea about it (even though URLs are supposed to be obscure, not pretty). But I don't think it's now worth making a breaking change to the spec for that now.

Nope, that's not REST. It's MVC'ish to the best but no REST at all.

~/objects/customers/31/actions/lastOrder/invoke => MVC'ish

Before arguing anything else... what's the 1st class citizen object for the above? Customer or Order?

Assuming it's Order then the url should be

~/objects/customers/31/lastOrder

which effectively identifies the last order for customer = 31. The resource as such is uniquely identified. You can apply a POST, PUT, GET etc to the above and it'll be the actual operation (not the url) the one providing the context.

~/x/y/action/sub-action/etc are MVC standards in the other hand used to identify which controller/action/etc is running a given piece of logic. MVC is not REST of course.

I'm afraid I don't follow your argument, here, Robert. You seem to be arguing that the format of the URL is important in order to claim RESTfulness. But REST has nothing to say about URL formats; REST is not about "pretty URLs".

But if you did want a URL to be surfaced that looked similar to ~/objects/customers/31/lastOrder, you could model this responsibility (of a Customer knowing how to obtain its last Order) as a property rather than an action. In this case its URL would be ~/objects/customers/31/properties/lastOrder rather than ~/objects/customers/31/actions/lastOrder.

The consequence of modelling things this way is that the property would be eagerly evaluated (when returning the representation of the customer) rather than lazily evaluated (when invoking the action).

Just to add to Dan's comments, Robert, the Restful Objects spec is not based on the MVC pattern - it makes no assumptions about the architecture of the server that implements the API. In the URL:

~/objects/customers/31/actions/lastOrder/invoke

the 'actions/lastOrder' is not specifying a controller action, it is specifying an action (i.e. a method) on a domain object (customers/31).

As it happens, the 'Restful Objects for .NET' implementation of the standard, as described in the article, does make use of ASP.NET MVC (in order to access the Web API framework), but it has just a single controller with a handful of generic methods - not a method for each of the actions that the domain model provides as you are inferring. The Restful Objects for Isis implementation is not, I think based on an MVC framework (though I'm not familiar with its internals and Dan might correct me on that).

The Restful Objects for Isis implementation is not, I think based on an MVC framework (though I'm not familiar with its internals and Dan might correct me on that).

Just to add to Dan's comments, Robert, the Restful Objects spec is not based on the MVC pattern - it makes no assumptions about the architecture of the server that implements the API.

In the URL:

~/objects/customers/31/actions/lastOrder/invoke

the 'actions/lastOrder' is not specifying a controller action, it is specifying an action (i.e. a method) on a domain object (customers/31).

Trust us, we *do* understand that REST relates to resources and representations. Restful Objects provides an automatic binding of these to an underlying domain model. When Richard says ".../actions/lastOrder/invoke" specifies an action, it's just shorthand for saying that it is a resource which addresses the result of invoking the lastOrder action on the underlying domain object.

Per 5.2.1.1 of Fielding's dissertation, "any information that can be named can be a resource [such as] a temporal service (e.g. "today's weather in Los Angeles"). Our action resources are exactly the same thing.

Adam Howard made the observation that we ought to have used "/invocation" in the URL rather than "/invoke". We agree with that; it might have prevented some confusion.

With respect to "~/objects/customers/31/actions/lastOrder/invoke" having a reference to a "hard-action" to provide context, that isn't true. The context comes from the representation from which this link was obtained (and the "rel" of that link). The fact that "lastOrder" is part of URL is convenient for those who might want to build clients using templated URLs rather than using HATEOAS, but one can also write clients that strictly follow HATEOAS and treat the URLs as entirely opaque.

Trust us, we *do* understand that REST relates to resources and representations.

Restful Objects provides an automatic binding of these to an underlying domain model. When Richard says ".../actions/lastOrder/invoke" specifies an action, it's just shorthand for saying that it is a resource which addresses the result of invoking the lastOrder action on the underlying domain object.

Per 5.2.1.1 of Fielding's dissertation, "any information that can be named can be a resource [such as] a temporal service (e.g. "today's weather in Los Angeles"). Our action resources are exactly the same thing.

Adam Howard made the observation that we ought to have used "/invocation" in the URL rather than "/invoke". We agree with that; it might have prevented some confusion.

With respect to "~/objects/customers/31/actions/lastOrder/invoke" having a reference to a "hard-action" to provide context, that isn't true. The context comes from the representation from which this link was obtained (and the "rel" of that link). The fact that "lastOrder" is part of URL is convenient for those who might want to build clients using templated URLs rather than using HATEOAS, but one can also write clients that strictly follow HATEOAS and treat the URLs as entirely opaque.

you have a situation where your uri ["~/objects/customers/31/actions/lastOrder/invoke"] just becomes inconsistent and confusing. .../invoke with OPTIONS? That'd be plain confusing

Even if you change "invoke" by "invocation" the situation does not get any clearer and that's just a result of trying to make the url to identify the operation rather than the resource.