Jean-Jacques Dubray just triggered a thought with a comment he made on Twitter regarding the rough ideas to adopt MVC 'ideas' in JAX-RS 2.0. He was worried that an MVC based approach to creating representations exposes the model to the service consumer.
Interestingly, this is only possible if the service uses generic media types. Specific media types sufficiently limit the kind of information that can be expressed in the representations and prevent the service specific model to be visible to the outside.
Specific media types enforce the resource boundary and prevent the service's domain model from leaking.
This is probably a much better argument against application/xml or application/json than the usual reference to the violation of message self descriptiveness.
November 19, 2010
November 2, 2010
October 23, 2010
October 13, 2010
October 12, 2010
Artifact Ownership or When Not to Use REST
Here is an indication of situations when applying REST is not appropriate:
When all artifacts that are affected by a possible change are owned by the same project (e.g. stored in the same source code control repository) then REST is not a suitable style.
An example of this is an application that contains a database component for its private use. Usually the database schema is stored in the repository together with the source code. If you face a need to change one, it is easy to change the other (from a developer coordination point of view).
The general take away from this is that artifact ownership can be used as an indicator for how appropriate a candidate style is.
(Consider how much the Unix command line benefits from the uniform API pipe and filter style: Completely decentralized developers can contribute components (grep, awk, sed, less, sort,..) without even engaging into agreeing on how the components talk to each other). The artifacts that make up the unix tool box are maintained by many different parties all over the world.
When all artifacts that are affected by a possible change are owned by the same project (e.g. stored in the same source code control repository) then REST is not a suitable style.
An example of this is an application that contains a database component for its private use. Usually the database schema is stored in the repository together with the source code. If you face a need to change one, it is easy to change the other (from a developer coordination point of view).
The general take away from this is that artifact ownership can be used as an indicator for how appropriate a candidate style is.
(Consider how much the Unix command line benefits from the uniform API pipe and filter style: Completely decentralized developers can contribute components (grep, awk, sed, less, sort,..) without even engaging into agreeing on how the components talk to each other). The artifacts that make up the unix tool box are maintained by many different parties all over the world.
September 1, 2010
August 25, 2010
GET /stock-quote/foo vs. getStockQuote("foo")
Consider the good old stock quote example from REST vs. RPC discussions. In both variants two kinds of coupling exist.
On the one hand there is the intentional coupling that causes the client to make the call to that particular remote thing and not just any arbitrary one. The intentional coupling is a human choice, manifested in configuration or code.
On the other hand there is technical coupling because the client software needs to know (aka be coupled to) the provided interface. Otherwise the communication would no be able to happen.
Given those two kinds or layers of coupling it makes no sense whatsoever to repeat the specifics already present in the intentional coupling at the technical level by giving that specific remote thing a specific interface.
Once the intentional choice has been made to talk to that remote thing the interface specifics can be factored away.
Why design, implement, test, maintain, document and explain more stuff if you can do the same things with less?
On the one hand there is the intentional coupling that causes the client to make the call to that particular remote thing and not just any arbitrary one. The intentional coupling is a human choice, manifested in configuration or code.
On the other hand there is technical coupling because the client software needs to know (aka be coupled to) the provided interface. Otherwise the communication would no be able to happen.
Given those two kinds or layers of coupling it makes no sense whatsoever to repeat the specifics already present in the intentional coupling at the technical level by giving that specific remote thing a specific interface.
Once the intentional choice has been made to talk to that remote thing the interface specifics can be factored away.
Why design, implement, test, maintain, document and explain more stuff if you can do the same things with less?
August 23, 2010
May 21, 2010
Amazingly Close
While looking up some stuff in the book "Integration Patterns" I spotted a tiny sentence that is amazingly close to REST. In chapter one on page 3 the authors (among them Gregor Hohpe, BTW) emphasize that from the point of view of integration the whole must be considered instead of solely designing for each integration between two applications in turn. The sentence is
I find this amazingly close to the notion of a user agent component consuming representations and capabilities provided by resources.
However, if you approach this same problem from an integration architecture perspective, the ideal application is a thin layer of presentation that consumes shared functionality or data at the enterprise level.
I find this amazingly close to the notion of a user agent component consuming representations and capabilities provided by resources.
May 12, 2010
Serendipitous Reuse vs. Reusable Services
The notion of reusable service builds on the anticipation of its uses
Reusable components notion focusses on using the same component for the same purpose often. There is no focus on use in unanticipated contexts. seren. reuse oth does that.
Serendipitous reuse on the other hand focusses on building components (that expose functionality) and using those compoents in unanticipated ways.
Reusable components notion focusses on using the same component for the same purpose often. There is no focus on use in unanticipated contexts. seren. reuse oth does that.
Serendipitous reuse on the other hand focusses on building components (that expose functionality) and using those compoents in unanticipated ways.
May 6, 2010
IRC Conversation on User, User Agent, Media Types, Application etc.
Currently I am trying to figure out the significance of the various aspects of a RESTful architecture with regard to modeling. Such aspects as user agent, media type, steady state, user, application, and application state. Tried to build-up an explanatory train of thought on that basis in an exchange with Philipp Meier on #rest IRC yesterday. It is the typical, hard to read, IRC conversation but you might find it useful nevertheless.
April 4, 2010
Steady-State
I have been meaning to write up for some time something about the notion of steady state. Now it ended up in a rest-duscuss posting.
Some references that I found insightful:
Slightly related from this blog: In Fear of Sub Requests.
Some references that I found insightful:
- Steady-State in Roy's dissertation
- Posting dealing with application entry points
- Web applications can have many entry points
- Steady-states are to be understood in isolation
- Steady-State, bookmarks, cool URIs(last two paragraphs)
Slightly related from this blog: In Fear of Sub Requests.
March 31, 2010
Why 'Action Resources' are a REST Anti Pattern
REST's uniform interface constraint requires the operations that can be invoked on a resource to be generic, meaning that the applicability of an operation must not depend on the actual nature of the target resource. The uniform interface does not prohibit additional methods to be defined but requires any extension method to be generic. PATCH or MONITOR (slide 16) for example are valid extensions, while ORDER or PAY are not.
Our OO-biased brains are trained to think in terms of classes and associated operations (Cart.order()) and it apparently takes a considerable amount of time for our brains to re-wire and think in terms of transferring representations to modify resource state.
As a result, people are tempted to come up with ways to map non-uniform operations onto HTTP's uniform interface. One offspring of such endeavor is the REST anti pattern of Action Resources.
I have not tracked it back to its origin, but the general form goes something like this:
Given an operation foo(), define a link semantic 'foo' that enables the server to tell the client what the URI is of 'the foo-action resource of some other resource R. Knowing the foo-action resource Rfoo, the client would then be able to invoke the foo() operation on R by means of an empty POST to Rfoo:
Find foo-action resource of R:
Invoke foo() on R:
So, why am I calling it an anti pattern?
Action resources are an anti pattern because the approach violates REST's self descriptive messages constraint. How so? Because the meaning of the POST request depends on resource state at the time the client learned that /items/56/foo is the foo-action resource of /items/56. There is nothing in the request that allows the server to understand the actual intention of the client at the time the server handles the POST request.
Suppose the client issues the above HEAD request at time T1, the server replies at T2 and the client receives the response at T3. By the time T4 the client sends the POST request to the action resource (and T5 when the server actually receives it) the server might have changed and is now looking at the POST with the empty body which translates to the client intention of telling the resource /items/56/foo to process this [empty body].
The server does not know that the request semantics depend on the server state at T2 when the server created the HEAD response and therefore cannot detect any mismatch between client intention and its own interpretation.
Our OO-biased brains are trained to think in terms of classes and associated operations (Cart.order()) and it apparently takes a considerable amount of time for our brains to re-wire and think in terms of transferring representations to modify resource state.
As a result, people are tempted to come up with ways to map non-uniform operations onto HTTP's uniform interface. One offspring of such endeavor is the REST anti pattern of Action Resources.
I have not tracked it back to its origin, but the general form goes something like this:
Given an operation foo(), define a link semantic 'foo' that enables the server to tell the client what the URI is of 'the foo-action resource of some other resource R. Knowing the foo-action resource Rfoo, the client would then be able to invoke the foo() operation on R by means of an empty POST to Rfoo:
Find foo-action resource of R:
HEAD /items/56
200 Ok
Link: ;rel=foo
Invoke foo() on R:
POST /items/56/foo
Content-Length: 0
204 No Content
So, why am I calling it an anti pattern?
Action resources are an anti pattern because the approach violates REST's self descriptive messages constraint. How so? Because the meaning of the POST request depends on resource state at the time the client learned that /items/56/foo is the foo-action resource of /items/56. There is nothing in the request that allows the server to understand the actual intention of the client at the time the server handles the POST request.
Suppose the client issues the above HEAD request at time T1, the server replies at T2 and the client receives the response at T3. By the time T4 the client sends the POST request to the action resource (and T5 when the server actually receives it) the server might have changed and is now looking at the POST with the empty body which translates to the client intention of telling the resource /items/56/foo to process this [empty body].
The server does not know that the request semantics depend on the server state at T2 when the server created the HEAD response and therefore cannot detect any mismatch between client intention and its own interpretation.
February 27, 2010
Classifying the CouchDB API
In the context of my Classification of HTTP-based APIs @hanonymity today asked me, how I would classify the CouchDB API.
Ok, let's see. Going to the HTTP Document API immediately reveals that the API definitely violates the hypermedia constraint (see last paragraph) because there is an API documentation in the first place. The only thing one would expect to see for a RESTful API is a set of media type specifications along the lines "The CouchDB API uses the following media types and link relations....which are specified here...".
Next, let's check if the API can be classified as HTTP-based Type II. The fastest way to verify this is usually to look for the use of only specified media types and it is immediately obvious that the CouchDB uses the generic media type application/json and not a specific one that would make the messages self-descriptive. CouchDB API fails the test for HTTP-based Type II, too.
This leaves us with the question whether the API is HTTP-based Type I or if we have to let go all hope because it must be classified as RPC URI-Tunneling. The thing to look out for is of course the use of action names in URIs. It does not take a lot of browsing through the API documentation to reveal that the CouchDB API designers knew what they were doing. The API very thoroughly leverages HTTP mechanics and we can happily conclude that the API is an HTTP-based Type I API.
Is it a problem that the CouchDB API violates two out of four of REST's interface constraints and is therefore not REST at all? I do not think so, because I would not consider achieving loose coupling between a database (backend) and the component that uses the database to be a very useful goal. At least not at the cost that you have to pay on the client side and also because there is strong coupling around the schema anyway between a database and the code that is using it.
However, I think CouchDB API shows quite nicely how an API can still benefit from the simplicity induced by HTTP-based Type I even if we cannot label the API as REST.
A note on the COPY method: It would be helpful to say in the API documentation that the COPY extension method is actually WebDAV's COPY method. And while we are at it, it makes also sense to note that COPY does not really fit HTTP because COPY is a method that works on two resources (Source and Destination) while HTTP does not support such method semantics. For example, caches would not understand that they need to flush the representations of the (now overwritten) destination resource.
This is not a question of RESTfulness though. It would be entirely possible to design an architecture that adheres to the REST style and provides methods that work on two resources.
Ok, let's see. Going to the HTTP Document API immediately reveals that the API definitely violates the hypermedia constraint (see last paragraph) because there is an API documentation in the first place. The only thing one would expect to see for a RESTful API is a set of media type specifications along the lines "The CouchDB API uses the following media types and link relations....which are specified here...".
Next, let's check if the API can be classified as HTTP-based Type II. The fastest way to verify this is usually to look for the use of only specified media types and it is immediately obvious that the CouchDB uses the generic media type application/json and not a specific one that would make the messages self-descriptive. CouchDB API fails the test for HTTP-based Type II, too.
This leaves us with the question whether the API is HTTP-based Type I or if we have to let go all hope because it must be classified as RPC URI-Tunneling. The thing to look out for is of course the use of action names in URIs. It does not take a lot of browsing through the API documentation to reveal that the CouchDB API designers knew what they were doing. The API very thoroughly leverages HTTP mechanics and we can happily conclude that the API is an HTTP-based Type I API.
Is it a problem that the CouchDB API violates two out of four of REST's interface constraints and is therefore not REST at all? I do not think so, because I would not consider achieving loose coupling between a database (backend) and the component that uses the database to be a very useful goal. At least not at the cost that you have to pay on the client side and also because there is strong coupling around the schema anyway between a database and the code that is using it.
However, I think CouchDB API shows quite nicely how an API can still benefit from the simplicity induced by HTTP-based Type I even if we cannot label the API as REST.
A note on the COPY method: It would be helpful to say in the API documentation that the COPY extension method is actually WebDAV's COPY method. And while we are at it, it makes also sense to note that COPY does not really fit HTTP because COPY is a method that works on two resources (Source and Destination) while HTTP does not support such method semantics. For example, caches would not understand that they need to flush the representations of the (now overwritten) destination resource.
This is not a question of RESTfulness though. It would be entirely possible to design an architecture that adheres to the REST style and provides methods that work on two resources.
Subscribe to:
Posts (Atom)