REST API Alternatives | Hacker News Reader

REST API Alternatives

blog.programmableweb.com

116 pointsbohinjc78 comments

A number of these points are not really a criticism of RESTful principles per se, but rather of typical REST over HTTP approaches.

1) Asynchronous APIs

There's nothing about REST that says that operations must be performed synchronously. If a client updates a resource via a PATCH method and other services are notified of the update via a web hook or a message bus (possibly including the PATCH or the full resource), the system is still following a RESTful design.

2) Orchestration / Experience APIs

A RESTful API does not need to require a separate GET for every individual resource. There's nothing wrong with implementing bulk queries that return variable projections of the server state tuned to the need of particular use cases.

Bulk modifications are trickier, especially when atomicity comes into play. But if atomicity is not a concern, then this is more of a transport problem, not a semantic one.

4) Binary protocols

Plenty of RESTful APIs (e.g., Twitter[1]) provide data in a number of payload formats. Choice of wire format is unrelated to whether or not the semantics of the API are RESTful.

[1] https://dev.twitter.com/docs/things-every-developer-should-k...

I'm fairly certain that when they describe an #2) Orchestration / Experience APIs they mean queries that return heterogeneous data, that one endpoint could retrieve the results of doing many queries, with many data types ie: GET /dashboard.json, retrieving all the resources used to assemble your dashboard page.

This is very much different than the normal REST philosophy of returning only homogeneous results. Much more RPC-ish.

the normal REST philosophy of returning only homogeneous results

Is that a thing? If 'GET /dashboard.json' obeyed the caching semantics of the resources it pulled together to present, and didn't have any surprising side effects, I'd still call that RESTful, even if it returned a rich graph of interesting data.

Yeah - but what if it returned a collection of orders also retrievable from /orders/search?date=today and customers from /customers/search?lastorderdate=today&totallifteimevalue=greaterthan,100000 and support tickets from /support/tickets/search?state=open

This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports.

> This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports.

This is nothing to do with REST. Read the Wikipedia article for a crash course.

I have, I agree. However the common design patterns for REST APIs encourage canonical URIs for resources, and discourage the same resource being retrieved from multiple locations - which heterogenous collections inevitably lead to.

Perhaps I should have said discouraged in the common patterns for implementing REST and REST-like APIs.

I wholeheartedly disagree with you -- you're ignoring hypermedia, an essential component in proper REST architecture.

If one correctly leverages hypermedia, you may and most likely will have heterogenous responses and relations. Side-loading relevant relations is highly encouraged and is a core component of efficient API design.

To your credit, I believe most of the information out there about REST and REST-like APIs discount how much work actually goes into building a proper REST API with hypermedia -- so we will always have half-baked design patterns that solve problems when doing REST incorrectly.

I think you are both a bit of in nitpicking mode, right?

I think the easy and normal and common path is to have canonical uri for ressources, and to serve agregated content for convenience or speed on other entry points, while adding to agregated content pointers to canonical uris.

No?

We benefit from being pragmatic. thumbs up

Not really. Returning hetergeneous data is perfectly RESTful if that is what the endpoint describes. You might want to be more descriptive in the URL, however:

/dashboard?type=orders&type=customers&type=support

With either some documentation explaining the differences, or even the return value itself describing what's in e.g.

{"orders": {"date": "today", "data": [...]}, ... }

What you return depends entirely on the context of your web service. If people are telling you to always return a homogenous set of results then they're wrong. You know your application better than some random guy on the internet.

You probably never heard about these, but these are the best for Binary protocols. If you know something else, or better please post.

BEEP: http://www.aspl.es/vortex/

BSON: http://bsonspec.org/ (Binary Json)

Ah BEEP. I had a grad school project to create a domain specific modeling language that allowed you to diagram the steps for communication and between to systems using BEEP. You'd define the order of messages and the content of the messages the DSML would generate C code that implemented an API to do the communication you'd modeled.

God how I hated grad school.

That sounds like an amazing experience you had. I can feel the pain! Had to write a custom compiler and backend and vm for it in school. And none of us had experience in C or Assembler. The compiler created a custom bytecode assembly that the VM had to run. Then another group made an FGPA and CPU that runs the code natively. Our prof's hobby was to write an OS for that board. But somehow we managed to do it. I still wow, when I look at the code. It makes me think.. how did I write that?

CBOR [0] is a proposed standard that seems much more efficient than BSON - check out the appendix [1].

[0] http://tools.ietf.org/html/rfc7049

[1] http://tools.ietf.org/html/rfc7049#appendix-E.6

checking out the rfc. cool, thanks!

http://thrift.apache.org/

MessagePack: http://msgpack.org

My only complaint for msgpack early on was that they didn't differentiate binary from strings, and they didn't explicitly state the format for strings (like utf8) ... other than that, it's a pretty nice format, though I don't see it particularly better than those mentioned in the article, or bson and others mentioned in this discussion.

Might as well add protocol buffers to this list http://code.google.com/p/protobuf/

and OSC: http://opensoundcontrol.org

and ASN.1 http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One

TLV: https://www.wittenburg.co.uk/Entry.aspx?id=390d746a-6a77-48b...

Far simpler yet readable, there is the tried and tested bencode [0], or tnetstrings [1]. There are a little less efficient than pure-binary (especially regarding integers) and have less features, but are easier to read and write, even for a human, in my opinion.

[0] http://en.wikipedia.org/wiki/Bencode [1] http://tnetstrings.org/

wow, I'm amazed by your responses. Kudos to HN & I wish all of you "Happy New Year and a Merry Christmas" (⌐■_■)-♉

Regarding 2) that's a 'potAYto potAHto' scenario, I think. The way I've used them in the past are to address performance concerns from customers. We have the general RESTful webservices that cover all uses cases, in that every object has an endpoint, blah blah, and the design generally conforms to RESTful paradigms.

Beyond that though, customers often request changes, additions, optimizations, etc., and as they're paying us money, we try to be as accommodating as possible. In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience.

To use the Github API for reference, to get the status of an issue, you have to query the issues for the repository, then the comments and events for the issue, and then the commit messages that are associated with the events.

An example of a non-RESTful paradigm is to simply JOIN the issue's comments and events and associate the relevant commit messages to the events so that they can all be captured in one call.

It isn't truly RESTful, but it's awfully damn convenient pertaining to customer overhead, and we still call it REST, and they don't bother correcting us.

An alternative approach that I've implemented in the past [0] (and found quite useful) is client-driven server-side inlining of linked resources.

What this means in practice is that the client specifies (usually with a query parameter) what related resources they are interested in, and the server can pre-fetch those resources and include them in the response.

Obviously there's some upfront development costs and your API needs to have a well-linked taxonomy of resources, but it allows the client to create these 'flattened views' on the fly with no further work on your part.

Edit: Just wanted to clarify that IMO this is a RESTful design because you are still using links to navigate your API resources, you're just writing a "smarter" server that can reduce the number of requests.

[0] https://github.com/BetSmartMedia/lazorse-nesting

edit: fixed link

> In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience.

This doesn't violate REST. The WWW is the canonical RESTful system, i.e. A client enters the API (a website) via a common entry point (example.com), navigates using links, and manipulates state using a shared understanding of a common media type (HTML and HTML forms). Think about it, when you go to a web page do you expect it to be about strictly one thing, e.g. when viewing a blog post, do you expect it to click a link to navigate to each comment? No, that would be insane. Does that make it non-RESTful? No. It is perfectly reasonable for a resource to be composed of other addressable resources.

Answer: This isn't even applicable. REST is still a good tool that applies to many jobs, use it where it makes sense, don't use it where it doesn't.

Better title: "Is using REST for everything a bad idea perhaps?" Turns out that yes, yes it is.

> Better title: "Is using REST for everything a bad idea perhaps?" Turns out that yes, yes it is.

For the vast majority of these uses, "REST" is a worthless and meaningless buzzword, so that's not a better title as the rise and fall of "REST" has nothing to do with it.

First of all, REST is pretty well-defined and is neither worthless, meaningless or a buzzword. Second of all, the rise and fall of REST doesn't have anything to do with the article either.

The entire article can be summarized as "At first we wanted to design pure things, but then we realized we need optimizations as well. Is this the dead of purity in design?" It just makes no sense at all.

> First of all, REST is pretty well-defined and is neither worthless, meaningless or a buzzword

Reading comprehension, you definitely don't have it. I didn't say REST wasn't well-defined or was worthless, I said most of the uses of the acronym are as a worthless and meaningless buzzword, having very little to do with REST itself. That is a very different issue.

And since most of the uses of the "REST" acronym have little to do with actually RESTful system, the rise and fall of the buzzword has no relation with the rise and fall of RESTful system (which, objectively, have had very little rise in the first place)

REST is not losing its flair, this article's four points focus on things that have mostly nothing to do with the huge bread and butter of web services, which is getting businesses to talk to each other and share data between entirely unrelated applications. #1 does not apply because these are simple data sharing services and async has nothing to do with it; #2 does not apply because these services are not internal; #3 does not apply because the other business you're talking to, RPC what? SDK-what? can I just send you my customer data in an XML file? #4 does not apply because see #3.

Then again, most "REST" as practiced for intra-business data is not really "REST" as far as purists would be concerned; while we at least do things like use HTTP error codes instead of an HTML page with "error" on it under a 200, I'd be laughed out of the conference room if I suggested our clients use a PUT instead of a POST. But who cares, as long as it's not SOAP.

Yeah. I've found a weird dichotomy in the general push to use "REST" for web APIs, but then certain aspects (true statelessness, for instance) are met with blank stares.

That's because "REST" is used as a buzzword for "Plain Old HTTP" much more commonly than to mean "REpresentational State Transfer".

I get just as many blank stares when I'm presented with a client that is using SOAP (btw, I'd say 100% of SOAP shops are .NET shops at this point), but their SOAP message consists of a single-element datastructure, the single element containing an XML document which is the actual payload, and I try to say, "that's not really SOAP..."

I'll give this to .Net though, at least their wsdl files are complete enough to generate a .Net client from.. that's about all I will give it in that regard... I can't stand SOAP, it's too cumbersome, and even more verbose in transport.

Several times, in the past couple years, I've actually written internal translation services in node.js against public soap endpoints that I can more easily consume (usually in C#/.Net)

Also, I've seen a lot of SOAP written in Java as well... Though the couple of PHP "SOAP" services I've had to consume have been the worst by far.

True statelessness? Even if you disregard POST as "not true REST", the PUT and DELETE methods involve changing state. REST is an acronym for "representational STATE transfer", and is all about dealing with state in an simple and transparent way, not about avoiding it.

The server can have state, but there should be no communication about the client state. This is most tricky regarding logged-in/out session state usually communicated with cookies. http://ruben.verborgh.org/blog/2012/08/24/rest-wheres-my-sta...

Also, I have never read anything implying POST requests are incompatible with REST.

Interesting that REST and JavaScript ended up in the same graph.

So I reckon the REST is dominating the field, SOAP is on the way out and JavaScript is the little upstart that could?

I don't think the person writing this article has any grasp on what REST actually is. If they knew they wouldn't be comparing it to the "Asynchronous APIs". I use asynchronous API's everyday. And some of them are RESTful and I prefer them over those that are not.

I keep trying to read the article and I have huge problems. I recognize the words, but I have no idea what the author is trying to say.

The async api bit is pretty off for a couple of reasons.

1. REST is not inherently uni-directional. This is especially going to be the case in the internet of things, where you're just as likely to have servers on both ends. 2. You can do server->client push with Server-Sent Events.

A link bait title with a graph that portrays REST growing faster than all other alternatives.

http://en.wikipedia.org/wiki/Betteridge's_law_of_headlines

If he's making the claim that "there are a number of initiatives, technologies and discussions that are starting to nibble at the crust of the de-facto standard that REST has become.", then surely he would have evidence of this claim?

To start with:

1. Label your axis, that graph doesn't say anything.

2. Maybe we should be looking at percentage change in the graph rather than whatever is being graphed here.

In context, the graph is intended to show the dominance of REST over time and not how it's losing out to any of the other items.

If that's the case, then his paragraph after the graph is not backed up with any data.

Instead, to me, it seems like he's trying to justify that statement with a poor microsoft office graph.

The graph shows old techs that currently serve as more-or-less substitute goods for REST. He's saying the four items listed below have a much smaller or even tiny but, as of recently, nonzero following.

What the fuck is JavaScript thing doing in there then?

I was puzzled briefly as to what JavaScript was doing there but thinking about it I've been doing some stuff with google maps and the API for that is mostly done with JavaScript objects.

Probably talking about JSON and similar formats like JSON API.

Which makes very little sense, since JSON is a content type it's mostly orthogonal to using REST, *RPC or whatever. You can do REST with JSON, XML, custom binary or ad-hoc textual payloads, and you can do RPC with exactly the same.

Sure. Another way to interpret "JavaScript" is that it means using one of the various data-binding frameworks. But who knows, I didn't write the article.

Relevant xkcd: http://xkcd.com/833/

the place where REST over HTTP fails badly IMO is batch operations and deep operations. when creating multiple entities at once, you cannot get back multiple location headers. and even if you could get back several headers, you have to re-request each of them via http to get their contents. it obligates you to be needlessly chatty.

deep ops on multiple objects complicate things even further.

i feel like once you get outside the realm of basic document storage (which is what HTTP was designed for), REST via HTTP headers completely breaks down into custom hackery for which there are no standards.

Yes, totally. It is completely lacking any mechanism that allows collection-level operations. If you want to create a bunch of resources you have to abandon the supported headers and return a list of ETags in the body, removing any niceties the client would've given you for standard "REST" support. Same for the Content-Location that you mentioned.

In practice, I don't think that stops people from making REST APIs that PUT/POST lists of sub-documents that each have an embedded ID.

For sending and retrieving multiple entities, you can use Multipart messages. The HTTP Location header would be a url for re-retrieving the multipart message, which is a representation of the resource which is the result of your request, and each of the entities within the message would need to have their own urls embedded within their representations.

I've used this approach for exactly the situation you're describing: batch operations that return multiple entities.

Async is an important category that deserves better coverage. Fundamentally, REST and the alternatives (SOAP, etc.) are all RPC protocols. They may make use of the RPC nature of HTTP or maybe like XML-RPC they shove another RPC layer on top. A remote procedure call sounds like the simplest component of a remote api, but it is not. In RPC you make a request and wait for a reply.

But with async, you send a message and that is it. This can be implemented on top of HTTP RPC such as with Websockets, but the HTTP layer is unnecessary. Messaging using the AMQP protocol is a nice alternative. You can open a socket and hold it open for sending and receiving messages. When you send a message, it can be received by an MQ broker like RabbitMQ for guaranteed delivery to whatever internal service(s) need to process it. And when some kind of result needs to be sent back to the message originator, the socket is open and ready to receive it. For those things where the app needs RPC, it is simple to send a message and wait for a reply message. But when all you need is a notification going out, or coming in, that works too.

While MQTT and ZeroMQ and others could be used, it would be nicer if the Internet standardized on AMQP at a known port (just like HTTP) and even included the use of an MQ broker with all the optional services (topic queues, persistence, guaranteed delivery) that can be provided.

For lower volume "push" data, it would be nice if there were a convention in REST for how to request a subscription in which you provided the callback URL where the updates would be PUT.

Not that this scales as well as message service "topics" (with multiple subscribers/listeners), but it's a start, and doesn't sound much worse than the load for point-to-point queues.

This is basically the description of webhooks

Cool, thanks.

All these are limited when you take a step back.

The concept of poking about with HTTP to try and treat it vaguely like a TCP style transport protocol is rather silly.

If you think about how "wordy" HTTP is, along with the standard RESTful verbs, you'll start to think "hmmm, perhaps this isn't the best way."

Websockets and if you must a bit of JSON (binary if done properly is lower latency and much more efficient) should be the way forward.

yes its a bit harder, but you know, its smaller, better, more efficient.

Depends: which is more precious: network bandwidth, or my development time.

High volume: custom-binary wins, just like you said. Low volume: REST/text wins.

There's something to be said for being able to try out your API in a web browser in 2 minutes. Compression also goes a way in reducing the volume of text, though not the latency of follow up queries that are too finely granular.

Small, sharp, tools swapping text is very unixy. Even if sometimes the response is a binary document :-)

This article just demonstrates the author's total lack of understanding of REST.

Let's start with asynchronous API. You can easily POST a request, get a new URL back, the just poll it until you get a result (returning 202 in the meantime). The simplest article explaining it can be found here:

http://www.infoq.com/articles/webber-rest-workflow

It's not even that hard - almost every website that generates non-trivial reports does it somewhere. REST hides all the implementation details behind simple resources (URLs in the HTTP world).

Orchestation: Go look up SPARQL. Yes, the language itself isn't pretty, but it's proof that you can orchestrate some pretty complex reports if you like. As pcl notes, you can do it with simpler URLs too. It's all down to the web service.

For SDKs... they tend to be reserved for the nastier APIs (usually involving XML).

Binary protocols? Seriously? There are entire theses dedicated to the fact that HTTP was designed to deal with this stuff. Go read the documentation on HTTP Accept headers.

I'm not surprised there are badly designed HTTP interfaces out there; but criticising the architectural style itself based on your own lack of knowledge helps nobody.

I'm having trouble understanding the continual claiming that REST is not asynchronous - which I guess means that REST is synchronous. Saying it once would be a typo, but several times and I start to feel there is a distinct difference of opinion between myself and the author as to what constitutes a Restful architecture.

    A typical RESTful API:
    PUT new data to resource x/y/z

    An asynchronous non RESTful API:
    POST job information for resource x/y/z
    GET status of job for resource x/y/z until status is complete.
    GET results of job for resource x/y/z

I think you left the realm of REST and reached out to the application level in order to make an non-existing case.

Your second example is only asynchronous in so far as you are oblivious to the completion of of the request, but that hardly makes it non-Restful. To me both of your examples are REST by definition.

It's all just relative though. If the resource is the job itself, then you have CRUD over REST for the job resource. The queue processing the job is a RESTful consumer as well, updating the job with information about the resulting new resource.

That is all RESTful. Whether or not its useful is a different question.

The next big thing: noREST.

My money is on RESTless, which in the form of RESTless web syndrome can cause sleepless nights.

I like to start with REST, I feel it's a great canvas, and a great way to think about what I am delivering. And if I can get the design to work within it's confines, then that's what I'll go with. It almost never ends up fully RESTful, and that's usually because the complexity required in the code would impact the maintainability. And to me maintainability is usually more important.

I love that REST is popular and SOAP is not (bad memories of SOAP). These days web sockets make streams and the unix process model of command parameters, environment, input and output possible.

A good module that uses this philosophy is:

https://github.com/substack/shoe

As with everything - pick the right tool for the job. It helps to have more rather than less tools.

Utter linkbait.

Its an OK article but I was really expecting to see some alternatives. I'm truly interested in something that compete with REST but was left wanting by the article.

I didn't think much of this article at all. I was expecting something possibly related to NetKernel or 9p, but was presented with... Thrift?

A more productive discussion might have started with Ext.Direct or Dojo RPC, but even those are just complementary channels, not alternatives.

Somewhat related question I've been meaning to ask. Why isn't xmlrpc more popular? At least in python it's incredibly easy to set up and to consume.

It depends what you mean by "popular", if you are talking about the number of XMLRPC service providers, then XMLRPC is far more popular as all wordpress installations have built in support for xmlrpc and are enabled by default.

I'm surprised this poor excuse for an article made it to the front page of HN!

I'm still a huge fan I do apply the resource think to most stuff I build.

its never been REST vs asynchronous Apis. You will probably use both in the same project for different usecases

RESTful services still work in those situations where they are correctly applied. Maybe what has happened is some of the less mature and more shrill developers have stepped back from their war on any Web service that doesn't fit their dogmatic rest-tard view of the world. There are plenty of valid XML-RPC based services that continue to run well despite the whining that someone somewhere did not yet have a ruby gem to connect their ruby on fails site to it and that it was simply unacceptable - and so complain on twatter they must!

So in short - no, REST works, use it in the right places, and remember kids - not every Web service or endpoint has to expose a REST based interface.

Simple XML-RPC interfaces can be OK, and they often have real documentation available, since they are not assumed to be magic, and that documentation will be needed. (we use several of these from a few vendors at work, they were not problematic to set up)

I've experienced a lot of pain trying to get working clients generated and configured from some magic WSDL (SOAP interface definition file), though. For a supposedly self describing standard, each time I have had to write a client, it was very much an "interesting" adventure.

My gut tells me there are many "Web Services" consultants who do not like REST because it simplifies things to the point where they are out of a job :-)

Reply on news.ycombinator.com