Hacker News Reader

Comment by PaulHoule | Hacker News Reader

This misses the elephant in the room.

The REST-inspired API that requires 10,000 API calls to do something that could be done in 1. This is a disaster from a simple performance perspective.

There is no simple way to build transactions on top of REST so if you need to do something that involves updating more than one data record you really are best off updating them all in one API call.

When you are writing a web front end this is all the more acute because choreographing a complex interaction with a server is a PITA with asynchronous communications.

If Fielding's thesis went in the trash and got replaced with "one click, one API call, update the UI" we'd hear a lot less carping about how awful the web platform is.

Careful reading of the http spec is a road to hell anyway because 80% of it is dark corners that aren't really used or implemented.

View on HN

You might want to check out GraphQL: http://graphql.org/. One of its killer features is the ability for clients to specify exactly the data it needs and obtain it in a single request/response.

Also checkout David Nolen's "Clients in Control"[0]. He approaches specifically those points mentioned, and pilfers ideas from Relay and Falcor.

[0]: http://www.datomic.com/videos.html

How I've addressed the transaction issue in the past is to expose it specifically as a transaction. For instance, POST /posts/transactions would contain a list of transformations to /posts and will receive a transaction id as a response. The id can be polled for success (/posts/transactions/:uuid) or results can be pushed to a browser. It is more work to be able to roll that back if one fails, but that's a coding issue not so much an API one.

I'd love some feedback on this approach. How do other people allow efficient mass changes?

This type of approach can be great. It is parallel to the idea to the "business is an exchange of documents", and the documents represent "transactions" in the sense of "an invoice", "a packing slip", "a deposit slip", "an order", etc.

> "business is an exchange of documents"

Did you just make up this phrase? It's really good!

You would probably like reading [1] by Dan North.

[1]: https://dannorth.net/classic-soa/

  Imagine you want to implement a vacation-booking service 
  as part of an enterprise system. The first step is to 
  remove any reference to computers or modern technology. 
  This will allow you to concentrate on the business 
  objectives of the service, without getting sidetracked by 
  technological considerations. In other words, it enables 
  you to separate the “what” from the “how.”

That's pretty great advice.

I've been saying it for a while. I talked to the developers of this product about a decade ago:

https://www.kuali.org/kfs

and that was the thinking behind how that system was built. Also this is the paradigm behind

http://www.enterpriseintegrationpatterns.com/

and it must predate the computer.

Indeed, I've recently had to use Google Drive API v3 and even though it's version 3 there's still a lot to improve.

Here's what you need to do to copy a file to different folder in C#:

            var newFile = drive.Files.Copy(null, fileId).Execute();
            var newFileInNewLocationreq = drive.Files.Update(null, newFile.Id);
            newFileInNewLocationreq.AddParents = newFolderId;
            newFileInNewLocationreq.RemoveParents = oldFolderId;
            var newFileInNewLocation = newFileInNewLocationreq.Execute();

To be fair it's just 2 API calls but rather verbose. And that's assuming all the calls work

> The REST-inspired API that requires 10,000 API calls to do something that could be done in 1.

That's not a REST-inspired API. (It might be an API inspired by the kind of naïve mapping of HTTP verbs onto the base tables of a normalized RDBMS schema suggested to people who don't understand DB design, REST, or application design by certain popular web frameworks default "REST" approach, but that's not REST's fault.)

There's nothing to stop someone putting resources on an api which do the one thing a client needs to do.

And what you describe nothing to do with REST, it's to do with overly fine-grained API design, without taking your users into account.

I have frequently seen it done in the name of REST, and had people argue that an effective API is an evil RPC.

First and foremost an API which services it's clients need well is a good API.

There are many people arguing things that aren't REST (e.g. pretty urls, media type based versioning) in the name of REST, and there are also (fewer) people trying to talk about things that are REST (e.g. HATEOAS) in the name of REST. This makes it (understandably) easy to blame REST due to the large amount of confusion.

In fact, I did a Bad Thing in my other comment by pointing out that REST-as-widely-understood isn't REST as all the mature individuals who are interested in REST APIs have taken to referring to them as Hypermedia APIs in order to avoid having to rehash the differences and kick off a flame war. I wouldn't have done it if OP hadn't mentioned HATEOAS.

If your application needs so many objects at once, yes, then you probably need something else. Or you just abstract it away through some POST interface alongside with the 10k resources.

> There is no simple way to build transactions on top of REST so if you need to do something that involves updating more than one data record you really are best off updating them all in one API call.

Yes, you can do that. I mean, if your really need to do that. Otherwise, your client should check the server resources for whether they represent to correct data. And you can always implement something like implicit transactions, where you create a transaction resource and append data to it or create new resources in a certain context.

EDIT: BTW. You don't have to do everything in REST. You can always "upgrade your protocol". So having a link myrpc://myserver:port is very valid.

> If Fielding's thesis went in the trash and got replaced with "one click, one API call, update the UI" we'd hear a lot less carping about how awful the web platform is.

Then we would end up building clients that always implement 100% of your RPC API. And we would not be able to move resources around. Implementing clients and servers would become an all-or-nothing thing, which really bad.

> Careful reading of the http spec is a road to hell anyway because 80% of it is dark corners that aren't really used or implemented.

By that you mean, that YOU have only used 20% of the spec so far? So why is it bad in general? I did not see these dark corners.

>The REST-inspired API that requires 10,000 API calls to do something that could be done in 1.

That should be a non-issue. Consider search queries. They are a simple GET request that returns a collection of many results in one response. You can do the same, you just need to define collection resources or collection semantics for existing resources.

The only challenge is handling partial failures, like when you POST 1000 things, and 22 of them fail validation. So each thing needs a status code in the response and some unique ID so that you can find its status code in the response. (That is separate from the overall request status code.) I have the client send a UUID and the server responds with a collection keyed by that UUID so that it's easy to find, for each thing that you sent, what happened.

on search queries, consider twitter search, I have read it is not REST because it is not idempotent

There was a surprisingly good talk on just that: https://vimeo.com/20781119

Where the server goes from requiring multiple requests to a single request without changing the clients whatsoever. So, I feel you're comment is on the right path (less http requests are better for the client and server), but might not realize that things can be optimized further.

This issue is greatly addressed with CQRS. http://martinfowler.com/bliki/CQRS.html

This can be resolved somewhat with a SOA or microservices, where one call from a client triggers multiple calls from one service to another. Sure there's overhead (which can be mitigated in a shared data center) but I think this is at least balanced out by modularity.

It's very different "inside the data center" or "inside the cloud" from "services provided to the network edge".

If you want: (i) any chance of all at building a system that works and (ii) happy users, you should codesign the client, protocol and client-facing server if you are providing services to the edge (Web, IoT, etc.)

Inside the data center you can do something else.

The key thing is that REST principles are orthogonal to "a good API", "a successful project", etc.

Reply on news.ycombinator.com