The trouble with APIs

| 6 Comments | No TrackBacks

I posted a couple of thoughts on Twitter and a few comments elsewhere recently as a results of a discussion on George Reese's blog and William's followup. I thought I'd repost these thoughts here with annotation as it seems to be evolving an interesting discussion.

1. REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation.

2. When someone says you shouldn't document a REST API, they're saying you shouldn't have an API. Not that you shouldn't document.

I mean by this, Network APIs. I also mean APIs that aren't re-implementable across sites. The point is that the uniform interface isn't just HTTP - it's a small number of evolving media types, and the goal is to enable sharing of information at a global scale. Your pet JSON format may not be the way to do this.

3. That said, RESTians saying you shouldn't have an API are somewhat vacuous because they offer no good alternative. Custom media types ain't.

4. Thus, IMO, until we have a workable generic media type or two for the 80% case of "REST APIs", we're just growing a frustrating mess.

In other words, I completely recognize that crafting a media type is a bit heady, and even still a custom media type for generic use is quite hard. With a REST API at least you get the benefits of HTTP GET (to some degree). It does the job, if all you want is a trendy vaguely hopeful way of building something for the long term without getting too bogged down in philosophy. I get it.

What I would like to see is a generic media type (above & beyond a "format" like JSON) to cover the 80/20 cases. This is seemingly contrary to where many RESTheads are at - they prefer often prefer opinionated media types, media types that "say something".

I'm actually asking for that too, I think -- say something about the programming model that breaks people's habits away from RPCs. Find a programming model that doesn't orient all "write-side" communication in terms of a flat list of actions, and into something that can be extended & shared across the web via hyperlinks and URIs. Hierarchical statecharts is my stab at this. There may be others.

5. From William's blog (with a couple tweaks)....

I've sort of half given up on REST advocacy because it's pretty impossible these days. People want to ship APIs that will be valid for the next next 6 months, not build systems that will evolve over a decade or more.

Jan Algermissen's comment about how when you've documented an API, you're not really doing REST, is actually spot on, fundamentally, but is met with ridicule. I can completely understand how vacuous the comment sounds if you just want to ship an API nownownow, are being short-term practically minded, or are just playing buzzword bingo with architectural styles. But if we actually want to leverage the benefits of the style, we'd work on the core issue of having a generic media type or two for these sorts of use cases.

If one is thinking of "how to methods map to my URI structures", we've basically lost the plot as to why we have HTTP, URIs and media types in the first place. The goal is to *eliminate* the API as we normally think of it. (It's not about a library of calls over a network).

Five points. The consequences of REST changes some rules:

1. The assumption can't be that the end user of your information service is going to be a programmer. Building an API bakes that assumption in how you expose your information or controls to manipulate it. The assumption rather should be that "this can be any agent of any sort". If your goal really is "I want a programmer to learn my API and program against this", then there's really no reason to use REST other than that it's trendy (and HTTP GET).

2. The assumption can't be that you will be the only site implementing your interface. The whole point of the Web is sharing information - publishing an API bakes in the assumption that YOU, the publisher, are in control. It is the consumer, on the other hand - the agent itself, that's in control of how/what the information is consumed or manipulated.

3. The semantics of the interface that need to be documented are the media type that you use to describe your data and links. The structure of your URIs really shouldn't be a part of said semantics.

4. But doing this in a custom media type implies #2, that you're the only person implementing your interface. Of course, every media type has to start somewhere, but it really doesn't help matters unless you understand that others may be *implementing* your interface, not just *talking* to it. Facebook's Open Graph, for example, is an example of a custom overlay media type that takes great pains to be generic in either direction.

5. All of the above is really heady stuff that is above most developer's pay grades, so it won't ever happen. The best we can hope for is some person/organization to step up with a generic media type or two + guidelines that help describe and document a Web of Data interface for accessibility by programmers. Call it a description language, if you'd like. Some RESTians don't like the idea of a description language. I think it's an essential 80/20 piece if developers are going to actually *use* the architecture the way it was meant to be used.

Currently (as I mentioned in my WS-REST keynote) I think some kind of hierarchical lifecycle/state machine might be the right abstraction for such an interface. I'd like to demonstrate this if I ever got past my day job sucking up most of my time. (But I may have an opportunity to work on this there soon.)

No TrackBacks

TrackBack URL:



good stuff here!

i've spent the last year exploring the details of designing hypermedia types for various reasons:
1) to learn the details
2) to explore why some media types "work" in RESTful solutions and others do not
3) to see if it is possible to come up w/ a media type that does over the 80/20 cases you refer to in this post.

my results (so far) can be gleaned here:

there are good and bad attempts there; things i'd not repeat and some minor successes (the domain-specific Maze+XML type works well for 'bots and even has a handful of independent implementations).

on another track, i am testing the notion of building semantically meaningful hypermedia using [X]HTML. IOW, not using a custom design, but using the most common hypermedia type already understood by the most common Web client (the browser).

the current state of that work can be found here:

it's early in the going, but i see some promise in some of the details. a group of folks will be doing a 'HackDay' in august to see if this "semantic HTML" can actually work when implementing clients and servers.

i'd be most interested in your feedback on these efforts and how you see them fitting (or not) into the ideas you mention here in your post.

again, great stuff and thanks for posting.

Take a look at RFC 6208 - IMHO this is the right way to standardize media types for a standard interface.

-- mark

My personal take has been that REST APIs are tempting mostly because they are easy to do from server-side, and much (most) of the complexity will reside on client side.
So: it is very easy for developers to expose things via REST. But to access REST services; this is actually where RPC style is much easier (and frameworks make life easier). With RPC, however, I would suggest reverse is true -- meaning that in both cases, complexity is highly asymmetric.

This is based on "having to eat our own dog food" -- I did have to create a client library for REST service we exposed at work; service that I believe is fairly well-designed (not by myself), yet amazingly complicated to make use of with just using basic HTTP primitives. Complexity comes not from basic CRUD things but from things like iterating over longer sequences (which must be paged); but it is rather soon obvious once you do write good solid client-side code.

If you're a Java programmer, then you'd probably use the JAX-RS standard API for REST.

And it's a great API, it's super easy to use, especially in combination with JAXB (Java XML Binding). It very easily converts your Java objects to and from XML and JSON with that. Doing a request and getting Java objects back is just one line of code and also exposing methods as RESTful web services is very easy.

It's a good example of an API that makes simple things very easy while not compromising more advanced usage.

Regarding your first point

"The point of REST was to *eliminate* specific APIs. Not cause their proliferation."

A literal interpretation of this point means normalizing everything into one single uniform model. I suspect you don't mean that. In my experience, it is prohibitively expensive to try to do so, and the net result may not meet each app's quality attributes.

The way I use and apply REST is to rely on various protocols and principles to drive interoperability and reduce friction to the extent desired by various constraints that the app needs to meet. In my approach, I rarely focus on formats and media types other than some simple guidelines on format design. This is a constant tradeoff between

(a) how much time I'm willing to spend to explain hypermedia
(b) benefits of hypermedia in the specific app
(c) performance and scalability
(d) current tech debt and cost of changes
(e) operational constraints (such as ownership boundaries, dependencies, etc.)

Over time, I've also to come to realize that REST is not prescriptive - it is constraint driven and hence can not be prescriptive. For me, this realization is far more empowering than selling REST as a set of five rules.

Leave a comment

About this Entry

This page contains a single entry by Stu published on June 9, 2011 5:45 AM.

WS-REST Keynote Slides and Recording was the previous entry in this blog.

Returning to the living is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

About Me
(C) 2003-2011 Stuart Charlton

Blogroll on Bloglines

Disclaimer: All opinions expressed in this blog are my own, and are not necessarily shared by my employer or any other organization I am affiliated with.