We've built a first version of an API that we have in testing at the moment, and it follows a lot of the things laid out in an ebook✝ and in the linked article.
The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should.
I've built a couple of very pure REST APIs in the past, but had a lot of developers pushing back and demanding something simpler. To not use media types so precisely, to be more accepting of what data is sent, to provide meta-data along with the resource (most seem to prefer an envelope), to prefer composite resources over very decoupled interfaces, etc.
This time, I haven't even tried to build a pure REST API. This time I've just mixed together the bits that developers I've spoken to liked and prefer. Adjusting as I went depending on how it was received.
That's the docs for it, and we get the arguments out the way right at the beginning. All we're trying to do is build an API that helps developers get their task done. We're not done, and I know it's not pure anything... but the feedback we're getting is far more positive than any pure REST API I've ever built.
✝ If you are willing to give out a fake email address then this free eBook is a great resource and has a lot of sane information presented clearly:
http://pages.apigee.com/web-api-design-ebook.html
The epiphany we had was that whilst machines do access
the API, the developer is always the customer and user.
Everything we do should help the developer, and if we
have to break rules to help them... then largely we
should.
Thank you, this articulates my disagreement with the idea of hashing all URLs so that client developers are forced to follow links returned by the API instead of generating their own URLs
There's nothing really wrong with RPC-like APIs. They're often much simpler to use in modern web development, for developers with access to documentation.
Hyperlinking has a few benefits, the biggest being discoverability without the need for browsing some documentation that explains how to build URLs, but it's not always the best possible solution for every application -- and it typically leads to chatty applications.
The only thing that bothers me, though, is when these RPC APIs are called "RESTful" just because they use HTTP verbs correctly.
This speaks to something that has baffled me for a long time. If we have to bend/break the rules of REST to make things usable in the real world (and I believe we do), why have REST as an ideal in the first place?
Why work halfway towards A, when we could define a more realistic B and implement it fully? We spend too much time justifying which parts of the holy book to ignore.
You have different objectives than a purely RESTful system does. If you had REST's objectives in mind, then the architectural constraints would be sensible.
But who has truly RESTful objectives in mind? Are there any widely used REST APIs that truly adhere? I acknowledge that there may be. It's just the ones I come across always make significant concessions. Sometimes people tell me that "the web as a whole" or RSS are examples, but those seem too fundamentally different from any API I might create.
The GitHub API is pretty damn close these days, and I can tell you that there's a very big company you've heard of with a two-digit person team working on a HAL-based hypermedia API right now. Twilio has been pretty good too.
There are lots of private APIs that operate this way; for example, much of Comcast's internal stuff is pure, hypermedia driven REST. But it's not open source, so you don't hear about it.
A YC-funded company, Balanced Payments, does an excellent job as well.
> those seem too fundamentally different from any API I might create.
Right! That's because you're primarily thinking of RPC styles, so of course it will seem foreign. Try this sentence on for size, from a different time period:
"But who has truly object oriented objectives in mind? Some people tell me that Smalltalk or C++ are examples, but those seem too fundamentally different from any code I might write."
That's not to say RPC is a bad thing: often times, it's just fine. But if you have the problems REST is designed to solve, REST will solve them much better.
The apigee doc is a great resource. The PDF is also indexed directly via google if you don't want to sign up: info.apigee.com/Portals/62317/docs/web%20api.pdf
I don't think what the developers are asking for is inherently not RESTful, as long as there is already a strict REST implementation. Adding composite resources in addition to the decoupled ones seems like a intuitive way to improve the usability of the API and the performance of the application (so there aren't so many API calls for common procedures.)
My own criteria is that RESTful interfaces should be easy to use from the command line using curl (or any other similar tool) - not that this is the main way an interface will be used, but it helps a lot with exploration and troubleshooting.
The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should.
I've built a couple of very pure REST APIs in the past, but had a lot of developers pushing back and demanding something simpler. To not use media types so precisely, to be more accepting of what data is sent, to provide meta-data along with the resource (most seem to prefer an envelope), to prefer composite resources over very decoupled interfaces, etc.
This time, I haven't even tried to build a pure REST API. This time I've just mixed together the bits that developers I've spoken to liked and prefer. Adjusting as I went depending on how it was received.
http://microcosm-cc.github.io/
That's the docs for it, and we get the arguments out the way right at the beginning. All we're trying to do is build an API that helps developers get their task done. We're not done, and I know it's not pure anything... but the feedback we're getting is far more positive than any pure REST API I've ever built.
✝ If you are willing to give out a fake email address then this free eBook is a great resource and has a lot of sane information presented clearly: http://pages.apigee.com/web-api-design-ebook.html