A lot of people say it is wrong for adding the version to the url. Is ebay wrong, is amazon wrong? I suppose so but in the end you are the one maintaining it.

For instance the schema will define say Customer as having an address and a phone number and the restul api will use the generated bean as input/output for PUT/GET. Now imagine if the structure of the Customer xsd/bean needs to change significantly and I want to support legacy calls and new calls. Ideally I would like one implementation on the server that can recognize the version and produce the correct xml. Maybe that goal is impractical. Maybe I need parallel implementations for the different versions, at least for the translations of my data model into the JAXB beans data model.

If I have a separate mime type for each schema will schema validation be easy to do? Will I still be able to consume/produce JSON or XML like I do now? If I use versioned uris then each url will be directed to the correct BEAN/Schema processing which can then call my more generic data modeling system.

Anyway I appreciate your thoughts on this.

Jon

But what does that actually mean? To me, this means that somewhere behind the API, in the application that the API provides access to, changes are going to be made to the data, following pre-determined business rules for doing so. So let’s say that today that means that the order is canceled and a refund check is cut to you and put in the mail.

Now let’s say that we have changed our business processes and deleting an order no longer automatically causes a refund check to be cut. You have to indicate what you want to do with your refund, either get it as a check or apply it as a credit to your account, by using a different URI. The original ‘/customer/73/order/12′ URI has not changed any as a resource, but it’s behavior has absolutely changed. For me, the consumption of a API is more than just the representation of resources – it’s also a way to interact with a/the application.

How, then, are the representations of resources and business logic to be reconciled? I ask this question without a concrete answer, because this seems to be a question with the area of REST API development to which there are many varied answers. I am very much interested in yours, and others, though, as I cannot learn and improve without others ideas. Thank you very much for your comment.

An alternate approach would be to pass a parameter in the URI, such as ?version=2.3 which may or may not lessen the problems clients will experience over time. Given the needs we had, and our anticipation that any “major” version changes would be because of changes in concepts, managing versions of the APIs as their own applications seemed a better way to go. I suppose as with all things, time will only tell.

Thank you very much for your comments. I have enjoyed the challenges to my thought processes they have introduced.

Putting versions in the URI violates opacity and forces clients to use out of band information (your URI construction schema), when all they should have to do is follow links.

Your example of the customer changing from having one phone to two illustrates a data modeling problem: a resource cannot simultaneously have both 1 and 2 phone numbers. What does Joe’s record look like in your database? If you start with the first form and make the change to allow multiples and Joe actually adds a second phone number, then it is incorrect for Joe’s resource to provide the 1st representation. Joe no longer has a “you have exactly one phone number” representation. You could have modeled this differently and included an attribute for primary=”true” and keep Joe’s representation. Then Joe has properties as a resource that aren’t in the original representation, which is absolutely not noteworthy. At least we know it’s the same Joe, because the URI is the same.

Asking “what happens when the business logic behind the POSTing to a resource does something different than it did before?” reveals the great beauty of REST, at least if you use HATEOAS correctly. The answer is nothing happens. The client is still presented with a representation uses hypermedia to define a menu of application state transitions. In the old media type representation the links must still be valid as well as in the new one. If you can’t do both, you must pick one media type or the other. Putting a version number in the API doesn’t solve anything in this regard and just confuses everything because intermediaries can’t tell you are talking about the same resource. It also means that you will have links to resources that CANNOT have a valid reprentation. Yuck.

The worst thing about putting versions in the URI is that web you retire old versions you break everybody that stored those links. The web depends on permalinks, use them! How can you possibly expect not to have massive client breakage this way.

REST is all about media types. Read the last few bullets of Roy’s fabulous post: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

If a change to the implementation logic behind an API could cause a client to break then your API is poorly defined. The API is leaking implementation details.
When a client makes a request it is merely communicating it’s intent, the API should make no guarantees about how that will be achieved.

What can change is application workflow, but because REST apis are hypermedia driven, the workflow is explicit in the response representations and can be managed in the same way as the data.

That being said I take issues with your mentioning the term “business logic” when talking about REST.

The term “business logic” is meaningless in the context of a RESTful service. REST knows about resources and their various representations and nothing else. If or if not posting a resource to an endpoint triggers additional business logic is beyond what is expressible in a RESTful context.

Of course nothing keeps you from *emulating* a service e.g AccountService#addTelephoneNumberToExistingAccount by posting the *resource* TelephoneNumberAddition – notice the transition from verb to noun here – to some endpoint. However, in the context of a ROA – Resource Orientied Architecture – as opposed to a SOA this does not constitute a service with some business logic attached to it. It simply means posting a resource.

Note that this reasoning leads to the same conclusion regarding how to properly implement versioning of a REST service (the term service in itself is a little unfortunate here, yet seems to be prevalent by now). Since REST does only know about resources and their representations, since representations are simply different views of the same resource, since resources are clearly central within a RESTful context, and finally since resources are uniquely defined by their URL, it seems natural to realize versioning in the way you described.

But I would argue that a scenario where a “service”’s version is incremented without changing the corresponding resource is beyond the realm of REST. From a RESTful point of view, absolutely nothing has changed, the underlying business logic – which has changed – is totally invisible to REST.

REST is not just a different way of publishing services. It’s an entirely different view of what a service *is*.