notes on my experience creating a RESTful API
- Leigh Dodds surveyed web services APIs for XTech 2005:
I wrote a detailed response based on my experience creating the Webjay API:
One point I didn't make in my response is how embryonic RESTful web
services are. The ideas which are common currency here have not been
accepted by implementors. I know this because implementing them
frequently led me to bits of technology that were blatantly broken from
a RESTful perspective, yet the bugs were not known.
For example, PUT handling in PHP is treated as a synonym for file
uploading. The RESTful idea that PUT is only different from POST in
terms of what it implies about state just didn't exist once I wandered
from these environs over to #php.
Similarly, using a broad range of response status codes meant that many
user agents overwrote my error messages, so that I couldn't have an
interface which was both user friendly and RESTful. I'm not just
talking about browsers, either -- lwp-request makes the same mistake.
Another problem was that there was no prior art to glean design patterns
from. For example, there was no programmer-level documentation on the
'hypermedia as engine of application state' constraint until Joe
Gregorio's "Contructing or Traversing URIs?" column on xml.com. That
was a great start, but it's only a start.
I hope these comments won't be interpreted as a bitter rant. These are
just my notes from the field.
On Sep 3, 2005, at 12:06 AM, Lucas Gonze wrote:
> Another problem was that there was no prior art to glean design
Yes, that is IMHO one of the biggest problems you face once you
actually start to implement a system. I am having similar problems
right now, especially with making principled (as opposed to
arbitrary) decisions when there are several choices to implement a
What I would like to work an (and hopefully will) is a methodology
for developing RESTful networked systems, including design principles
(beyond RESTs architectural constraints). Ideally this would also
include the issue of domain driven design, where the domain model
should not only be used to derive MIME type or RDF namespace
semantics but also the actual deployment of components [obviously not
cooked yet, but that's where I would like to go].
> For example, there was no programmer-level documentation on the
> 'hypermedia as engine of application state' constraint until Joe
> Gregorio's "Contructing or Traversing URIs?" column on xml.com.
> was a great start, but it's only a start.
I think (one of) the major design principle is the goal to minimize
the impact that domain model changes have on the components (it is an
advantage if you can deploy them once an then more or less 'forget
about them' since you know that
- they are immune to backward compatible changes to the
message semantics since they will ignore whatever they do
not understand (partial understanding)
- they do not make (heavy) use of hardwired URIs but instead
discover them from the hypertext they process
- can be functionally extended by sending them code (assuming
clients before you deployed them; that way using the browser
style for non-human controlled client components)
 One thing I have been thinking about is an engine that would
provide to the client the capability to transform RDF graphs it
receives from newer namespace versions to the one it understands,
given the server would send the code to do the transformation.
> I hope these comments won't be interpreted as a bitter rant. These
> just my notes from the field.
> - Lucas
>  http://www.xml.com/pub/a/2005/04/06/restful.html.
> ------------------------ Yahoo! Groups Sponsor --------------------
> Most low income households are not online. Help bridge the digital
> divide today!
> Yahoo! Groups Links
Jan Algermissen, Consultant & Programmer
Tugboat Consulting, 'Applying Web technology to enterprise IT'