Designing HTTP interfaces and RESTful web services
slideshare.net
slideshare.net
I think the reason JSON apis caught like wildfire was to get away from the many pitfalls of over-architecture of XML in relation to SOAP, attribute/element dichotomy, namespacing with multiple nodes for the same value and general bulkiness. Parsing xml in javascript, scripting like actionscript and more is being mean to your consumers where JSON becomes objects they can use immediately. Are you making the API for your consumers or Roy Fielding?
Granted Roy has helped me win many arguments and I am on board, it just takes time for these things to catch or be able to be used 100% to the spec as with any standard. I see REST more as a pattern much like the GOF patterns that evolved from actual work to become patterns. But strictly adhering to patterns or standards is not always business/market/product capable at the time.
I don't see being true to what I deem a biased view of what REST is over making your api dead simple. Simplicity is missing more in software than long term thinking. This is mostly simple but adding in the requirement for representational view to be deemed 'REST certified' is a bit snouty.
RESTful on the client was only recently available so all this is evolving (i.e. setting client headers and anything other than POST or GET wasn't even possible until a few years ago consistently in browsers). I think the wrong direction to go is to get too SOAPy about services. Most heavily in use apis on the web still have to bend more RPCish because the market required it at the time, with time things will move more towards REST now that it is possible to perform a DELETE or set a header from more consumers.
If real programming standards weren't both academic and market based but solely academic then we'd all be using Java to code up our SOAP generated services which in term didn't work with other platforms like .NET services.
KISS prevails always and once again... JSON is a member. And I am down with HATEOAS but what a bad acronym.
I am big on REST I will reiterate, I included it in my own thesis in 2006 and the reason why I like it so much is it does make services more simple. I have been pusing it, JSON and simple apis since SOAP made my life hell (but was a needed notch to get away from proprietary formats and opening up data). Engineers jobs are to take complex things and make them simple to use for not just other engineers but non engineers without abstract thinking.
I just think repeating the historical mistakes of web services like SOAP can happen to JSON, REST and more if we don't check it with the current market and just keep it simple. I think REST is the way but you can have some flexibility for pragmatic business needs, lots of programmers cannot put business needs over ego at times. Don't tell people they aren't able to call it REST if it doesn't spit out ATOM representation and only use Accept headers.
Tell your business partners when your api doesn't work in a game engine because the http library didn't support headers that it isn't a true service and the client is unworthy of connecting. Or you could just use headers first then have other options/endpoints/abstracted urls to resources for non capable clients and still call it REST.
In the market today most big apis are RESTish RPC and that version will win because that is what is the most common service available today due to consumer/client demands. Granted it's not pretty.
It even quotes Roy saying "Many of the constraints are directly opposed to short-term efficiency" and that most developers don't care about goals of rest.
I think points you're making are fine, but they're acknowledged in the presentation, so your rant is unnecessary.
I think the author did a good job presenting actual (you can say academic) REST, rather than a more popular and simpler to create "JSON-over-HTTP database" pattern (which is fine, but shouldn't technically be called "RESTful").
Do you really believe if you don't use Accept headers as the only means of version that you aren't REST? Is REST a pattern you can follow only to the letter of Roy Fielding's dissertation? If so there might not be ANY REST web services out in the real market that are big. Everyone is just doing RESTish or RESTy instead of certified RESTful.
Also I believe HN is a place where we can discuss articles and pragmatic opinions about it, I don't assume everyone just agrees that this presentation was the one and only way to do REST like the author was stating. I stated my opinion to that. If this is the only way to do REST, simple services then the whole web isn't doing it yet.
This turned out like a rag on REST which it is not. It is a rag on over complicating and ivory tower architecture. REST should be about simplifying web services for consumers as well. When you get to implementing your RESTful service to support all clients, even with the current marke,t you will find it doesn't fit everywhere.
A service should be liberal in what it accepts and conservative in what it sends. The market deems when it is necessary to tighten the standards, right now his interpretation of it is too narrow.
We need a new standard called SIMPLE: RESTish/RPC, HTTP based, simple messaging (JSON/YAML), urls can be abstractions (in fact it is better to hide your models in most cases except for an admin scaffold), consumer aspect based routing (login, signup, myinfo) all the way from front end to service abstraction. Accept and formats can be in headers first and fall back to url based. Kinda like how systems like twitter, facbeook, 37 signals, etc do.
I agree we need a good word for those HTTP-but-not-quite-REST APIs. I simply call them "HTTP APIs", but maybe SIMPLE, NoRPC or REST 2.0 will take off ;)
Generating Java WebService client given .NET XSD/WSDL was a 5 minutes job. Ditto for the other way around: generating an XSD/WSDL from Java to be consumed by other parties was a 5 minute task (how the other party consumed it not of our concern).
OTOH, coming up with a good RESTful interface is proven to be very challenging. Some people coded up their REST interface to be like "/some/url/getInvoice", while others coded up their REST interface to follow Rails a bit more given their background. But sometime this second group that follows Rails convention were wondering how to implement the right REST interface for certain use-cases such as updating a boolean that is part of another bigger domain model object:
- What is the URL will look like?
- What kind of operation?
- What is the parameter?
- What is the return value?
That's what Roy's talking about when he says REST is about designing on a long term scale. A client that uses a RESTful API should be parsing and navigating the representations dynamically, which allows them to handle changes in the representation gracefully. The clients can never handle semantic changes to the API, but they can handle structural changes.
What do I mean by that? If you provide links for paging, and the link for the next page uses rel="next", that's the semantic meaning for the link. Your client has to hardcode the knowledge that it needs to find the link with rel="next" in order to go to the next page. But, it doesn't matter where that link may appear in the page, or what the url for that link happens to be. These are both structural details that can change over time without breaking your client.
Your example also seems to be optimized for REST.
I am not suggesting that SOAP is much better.
You lose a tweet or two here or there, not a big issue. JSON will do it just fine.
Your bank on the other hand will prefer XML that can be validated with XSD and you don't lose your car payment. Or your salary deposit.
It's not academic, it's a matter of use case.
But yes, in terms of financial/gov't there can be other requirements. Lots of those systems are more enterprisy and may need that. However the same things can be done no matter the format, it still happens in EDI for instance over EDIHTTP/AS2 for POs and Invoices to Wal-mart everyday, it is not locked to XML and validated schemas only. JSON can be used there as well such as stripe.com does. The messaging is independent from a solid system really, I am just talking what is easier for large web consumption.
This isn't necessarily the best design in the world, but you also can't ignore the real world requirements of operating a site as large as twitter. I suspect it would be more expensive (in many ways) for twitter to direct all traffic to twitter.com and then route it internally based on the accept header.
Versioning on the accept header is, in my mind, the most controversial part of "Hypermedia" API design. Custom mime types add a lot of complexity in the real world, from both the client and server side perspectives. And yet, changing the path in order to access a new resource has many downsides of its own. There's also a question of scale -- adding a bit of new information to existi
unless the resource in question is exposed as an endpoint, the url and verb are handled by the link or form discovered by the client, and invisible to the client.
as for versioning - versioning the mime types is a useful thing, but it does still make sense to use a different url if you are using different links and forms to navigate the service.