Archive for category RESTful Design
What constitutes a version change?
Posted by rberk in RESTful Design, Web Services on May 28th, 2009
Recently, in the ROA technical group, we discussed what constitutes a version change in our RESTful services. Many of us have adopted the versioning convention of embedding a version integer in the URI as supported in the Richardson and Ruby book
/student/v3/course
So when do we need to change this integer? As we add new data elements to our fledgling services, we are concerned about a proliferation of versions, and in particular, URI’s. Do we need to change URI’s with the addition of each new element? To do this too often seems to add unnecessary complexity and maintenance cost. Instead we have decided that minor changes that are “additive” do not necessitate an integer version change and consequently do not require a change to the URI.
By “additive” changes, we mean changes that wouldn’t break xpath queries based upon the class attribute:
/html/body/div/span[@class='foo']
as opposed to a queries based upon the ordinal relationship of elements
/html/body/div[2]/span[3]
(We consider the use of queries based on the class attribute a better development practice.)
One concern is that even if we don’t break clients with a version change, how do we communicate the change. We are recommending the inclusion of a programmatically parsable xhmtl version element in the root of each service that describes a fuller version, perhaps with major, minor, revision, and build.
<div>Service Code version:
<span class="service_code_version">3.0.1.26481</span></div>
That should allow for programmatic detection of version changes. And, of course, we still advocate application support email lists to communicate any change in service contract.
What do others think?
Financial Web Service development status
Posted by ssteph in RESTful Design, Web Services on April 9th, 2009
Work continues on the Financial Web Service targeting “summer” for release. There will be six resources that comprise v1: budget, budget search, organization, organization search, vendor and vendor search; inquiry only. A data dictionary will be provided within the resource representations. The service will be publicly available. A couple of clients have already signed up to start using the service. If you are interested in using the service or reviewing the proposed representation attributes, let us know!
What is ROA (Resource Oriented Architecture)?
Posted by ttchang in RESTful Design, Web Services on March 24th, 2009
Since this blog launched last week I received a couple questions asking us “What is ROA?”. Since this blog is named “On the ROA” it seemed necessary to answer that question!
So what is ROA?
“Resources Oriented Architecture is a way of turning a problem into a Restful web service: an arrangement of URIs, HTTP, and XML that works like the rest of the Web, and that programmers will enjoy using.” – Restful Web Services (Leonard Richardson, Sam Ruby)
Our answer is that Resources Oriented Architecture (ROA) is an overall system design that embraces RESTful design philosophy. It has a lot of overlap with Services Oriented Architecture (decentralization and small interoperating services) but it means that instead of treating our functionality and data as service calls; we treat them as resources in the RESTful sense.
In the early days of grappling with web services here at the UW many of us working in various IT departments investigated SOA (Service Oriented Architecture). During this investigation we were introduced to Pete Lacey, who introduced us to Restful web services. This led to a SOA workshop which many developers and technologists on campus attended. The idea of building Restful web services vs building SOAP web services on campus seemed to take hold probably because of the heterogeneous nature of computing here at the UW. The need to be technology agnostic in our approach to deliver data and automate processes seems to make a lot of sense in order to ensure all parts of the UW can take part in leveraging information services. In addition, the REST (Representational State Transfer) approach to constructing web services allows a very simple interface between systems (services and clients), and it scales well.
Following the Restful path, we soon discovered that there was a term that was being used to describe an architecture based on Restful design practices: Resource Oriented Architecture.
With that said, the bottom line is that the UW has a lot of information that people and applications need to access in order to keep the UW well positioned for the future. That information needs to have a low barrier for access and at the same time be safely accessible. We believe that planning our data access needs for the future using ROA and building web services based on a Restful design is one way that can help us meet this need.
Error Documents for RESTful Services
Posted by mcrawfor in RESTful Design, Web Services on March 18th, 2009
Where you have software, you have errors. Web services are no exception. When talking about the design of RESTful web services, a problem quickly rears its head:
HTTP Status Codes are Pretty Inflexible
Since we’re following RESTful principles here, we already have a tool to communicate these errors: the HTTP status code. Now – this is a pretty good system as far as the transport protocol goes, and the formally defined codes available cover lots of the generic cases such as “I just don’t know what you’re asking for” and “I can’t let you see that.”
But I’m pretty sure you see the problem. My service for letting instructors grade a student’s homework may choke on a request that tries to set the grade to ‘4.2′ and there’s no HTTP status code for “Grades don’t go that high.” Some people have tried to extend or build on top of HTTP to cover some important domains but you can’t cover everything (or get everyone to use your extension).
Luckily, HTTP accounts for this with some general status codes such as “400 – The request could not be understood.” HTTP recommends that you provide not only a status code of 400 but a document body that describes the error. When a client sees a 400, it can dive into that payload to get more information.
Similarities Emerge
The ROA Technology group recently looked at the error documents that a variety of services produce, and found that the approaches were quite similar. Based on examples from the Student Web Service, Catalyst, and Amazon’s Web Services offerings, we would like to offer the following recommendation.
Recommendation
The format should be easily parseable. We recommend XHTML because of the huge number of tools that know how to parse and display it, but many other formats would do just as well.
Three distinct elements for three distinct audiences. Three types of viewers will probably see your error messages: HTTP clients that are actually doing the transport, programmatic client code that understand the content or purpose of the service, and humans who are programming to, debuging, or using your service. So:
- error_http_code Include the numeric HTTP status code used to report this error. Anything that knows how to react to generic HTTP codes will thank you.
- error_key A short, unique string that identifies the error. This should be used to allow client code to programmatically react to errors in at a more granular level than the HTTP status code. These should remain as static as possible to avoid breaking code!
- error_description A human-readable chunk of text or hypertext intended to help a user of the service identify and resolve the error.
These documents could be extended with new elements. Your service might have good reason to include other useful bits of information, and we encourage this as appropriate.
An Example!
Recommendations without examples are no good, so:
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>InvalidHomeworkScore</title>
</head>
<body>
<div class="error_http_status">400</div>
<div class="error_key">InvalidHomeworkScore</div>
<div class="error_description">
The score you included in your request was not within the acceptable range
of 0 - 100 points.
<br/>
Please refer to the
<a rel="documentation" href="http://example.com/scoring-docs">scoring documentation</a>.
</div>
</body>
</html>
Great! Now, my HTTP library can avoid caching this since it’s an error, my client code can notice “InvalidHomeworkScore” and tell my end user that they need to try again, and when I was programming my client, it was easy for me to figure out what the heck was going wrong.