RESTful API Server - Doing it right

Is RSS difficult and complicated to learn and use? Now think what a pain it would be to develop a feed reader if each blog had its own "simpler" ad-hoc schema.

Standards don't have to be complicated, especially if they use an extensible encoding like JSON or XML so that instead of having the kitchen sink they can remain simple and be extended for specific purposes if really needed, without affecting generic clients.

I'm happy to change a server's content-type from application/json to application/vnd.my-adhoc-service+json, but that won't change the client's need to read my documentation and play with the service before they can figure out how to use it. That's true even if I move the documentation out to an RFC.

The end goal is for different services to agree on standard formats for common resources. Using custom mimetypes is a step in the right direction because it decouples the format recognition and parsing from the service-specific code - it allows clients to use more modular code that works across different services with plenty of reusable code.

Is it terribly important? No. But since the costs are essentially none - changing a couple of strings here and there - not doing it seems unreasonable to me. You asked why, I ask why not?

A more apt comparator may be WSDL, which theoretically allows a SOAP web service's remote procedure calls to be discovered programmatically but in practice is such a messy, complicated, leaky abstraction that it's often easier just to build XML templates manually and POST them to the endpoint.

Well, two points:

Firstly, I think WSDL (and WADL) are working at the wrong abstraction level. I think one of the reasons why REST is cleaner is because unlike SOAP it's data oriented, not RPC. And I believe it's possible, as long as your API is data oriented too, to map that to generic formats that don't feel messy.

I had already mentioned RDF (Resource Description Framework), but I'll mention it again; RDF is a layer between the serialization and the concrete schemas, giving very specific but open ended semantics to its documents.

Unlike WSDL, it's very simple: it consists only of four concepts: triples, which are composed of objects (which is always a resource, and is represented as an URL), subjects (which can be other resource or a literal value) and a predicate (which relates that object with the subject in some way, and which are specified by a schema). Then, a document is just a bunch of statements about one or more resources.

This model is hypermedia (since it clearly points to resources), and it's at the same time constrained enough to not end up being messy, and open enough to define mostly anything. I think it really captures the sweet spot.

There's no JSON serialization, unfortunately, but I like Turtle[1].

---------

The second point is that even if this day dream of mine never comes to pass, I think we'd still benefit a lot from using more of those standard "schemas with specific, narrowly defined purposes" and keep the custom formats to when they're really needed. Instead of defining your own user profile schema - which 99% of the APIs out there need - why not just share a single format, which can be easily:

1) Parsed by generic clients, libraries and plugins

2) Shared between services and applications

But for that, mediatypes make perfect sense, since they make it easy for a single HTTP client to dispatch the responses to the right readers, without involving a bunch of hairy rules that say "when response is JSON and the service being called is X, call parser Y".

This post is against WADL, but I think it expresses that power of using proper mediatypes: http://bitworking.org/news/193/Do-we-need-WADL

I'm struggling to understand the benefit of a custom media type beyond merely satisfying one of Roy Fielding's constraints. If the only reason to use a custom media type is to satisfy a constraint, the constraint might be more ceremonial than useful.

I might be wrong, but I'm convinced some great things could come up from it. Unfortunately, I doubt that anyone will seriously explore the possibilities unless there are already many APIs with support for it, and in typical Prisoner's dilemma style, very few API developers will consider supporting it unless they see a short term benefit.

If two web services are identical except one serves `Content-Type: application/vnd.some-arbitrary-format+json` and the other serves `Content-Type: application/json`, I get suspicious about the benefits of REST when people say the latter is doing it wrong and doesn't deserve to be called RESTful.

Well, I think as long as it supports HATEOAS it's RESTful enough, but on the other hand, I can see the their point. There's nothing wrong with not fully implementing REST, but still calling it REST gives false expectations to the clients.

Of course, at this stage nobody expects a RESTful API to be actually RESTful, but then again that's the problem, isn't it?

Well, sorry for the WOT :|