Saturday, November 29, 2008

RESTful thoughts - versioning


I've done a lot of thinking on versioning for an API I've been working on. I feel that the mystical nature of API versions should not be the last consideration of an API implementation - why do that to yourself; why do that to your customers?

So how does one approach versioning for the "Programmable Web?" What do your users do when they come to a fork in road?

Approach it using basic considerations of any API architecture (not holding true to Zachman's approach - we'll handle the where, when, and why some other day)
  • Who - always consider the consumer. I would consider myself a clown if I didn't listen to the users of the API. Beyond patterns, best practices, and textbook principles - the user has perspective that exists outside of any "should be" reality. They understand the serendipitous side of your API so-to-speak. Side note: This consideration goes way beyond versioning and down to the deep roots of the API's foundation.
  • How - What are the options. If I have half a dozen choices, what are some proven patterns, what is the industry moving on? For instance, authentication for an API - let's say you have an API that will be used by open-source consumers for social mashups that share resources. The seemingly obvious option would be OAUTH. You don't eat soup with a fork (unless you're eating a soup sandwich) - why should you skip thinking about the appropriate use of technology for an API
  • What - Typically if it is a web-based API, you'll be dealing with resources - especially when you're dealing with an API based on RESTful principles. What type of payloads are you dealing with? Are you going to implement resource extensions (.json, .xml, etc...)?

What are the options:
  • URIs
  • Custom Headers
  • By way of HATEOAS (Hypermedia as the engine of application state - one of the basic proposed constraints of REST, or some other resource driven-hypermedia makeup)
  • Request definition
  • etc...
URIs
http://api.mysite.com/v2/people/1 <- like
http://api2.mysite.com/people/1<- not a fan

Custom Headers
Request.Headers.Add("X_HTTP_MYAPI_VERSION","2.0")
<- Though explicit, less visible, would be buried in code

HATEOAS
While, by default the HATEOAS principles are built-in to a RESTful API - think of it like a page on a website and the context of that page tells what can be editied, created, viewed, who you are, etc...

So, in REST one of the parts of this principle is how your application will interpret n * document representations / formats that you API supports.

For instance, I could create a document representation with versioning for People information coming out of my API in an XML format: application/MyAPI-person-v3+xml

I understand the RESTful approach to explicitly seek a resource, it still feels like it is breaking some low level HTTP rule - my take, HTTP has worked this long for a reason, I don't feel very comfortable making up content types for a versioning implementation.

But... media-types seem to be a good option because we are dealing specific resources with specific implementations.

Request Definition

Probably my least favorite. Basically, you put all information about the resource in the parameters (NOT the header) of the request. This approach pretty much does the same thing as the other options, except, makes it more difficult for the programmer to implement. This pattern is commonly used on pin-point APIs where there is only one interface to consume - basically 1 URI for multiple resources - RESTifarians, please don't get upset at me for even mentioning this as an option for RESTful versioning.

So to the RESTful "Who" out there - what are your thoughts on a versioning pattern?

Tuesday, November 25, 2008

Burnt toast and expired milk


I was marveling at the mysticism of software dev yesterday when I stopped by to talk to our scrum master about some technical debt we've accumulated.

After talking to him, I realized something... Software is a product with a shelf life, but often times we forget to put the expiration date on the product.

In the Agile world, most things are done in the context of an iteration, leaving little time (unless planned) for re-architecture. We approach an ongoing software project as if it were immutable - unchangeable foundations, stale functionality, accumulation of technical debt <- all point to that. This whole web 2.0 thing (whatever that means) has us pumping out software on fragile foundations, proving that "the next big thing" is built on "that old weak thing." see twitter woes
"Twitter is, fundamentally, a messaging system. Twitter was not architected as a messaging system, however."
Why is it when your car warranty runs out it begins to break down, or when the 1 year limited warranty ("limited warranty" - what does that even mean?) on your toaster expires you begin to get burnt toast?

For our users, let us commit to tossing out the expired software (all or parts) and spend some capital on new / fresh development.

Would you go back to a restaurant that served you expired milk?