Hacker News Reader

Comment by pixelmonkey | Hacker News Reader

Not a book, but the best recorded talk ever given about API design is (IMO) by Joshua Bloch, in a 2007 tech talk at Google. "How to Design a Good API and Why It Matters".

He was one of the creators of the Java Collections API and the Java Executor Framework, two of the most durable and most widely-copied APIs ever. That may not seem relevant for an HTTP/REST API, but it is. The design principles are timeless. Here's that reference:

https://twitter.com/amontalenti/status/1260030567501840386?s...

When I had to design a widely-used "HTTP/RESTful" API a few years back, I wrote a summary of the design principles here. It also includes a reference to an old O'Reilly book on the topic, which I summarized:

https://www.parse.ly/help/api/restful-apis

View on HN

I really cannot agree with the "just use GET" suggestion. GET must not be used for actions that modify the data server-side. Also, POST and PUT means some action is or is not idempotent.

Using different methods than GET is easy in the browser (easier than JSON-P) and avoids a huge class of problems that come with abusing GET.

Yes, honestly this was written at a time when browsers (specifically, the XHR API) did not support non-GET requests reliably at all (e.g. pre-CORS), so there was no other option. (And once you publish an API, it's hard to change.) You're right that today there is better support for POST/PUT, although there might still be some issues lurking in the corners.

I don't think there's ever been a time browsers haven't reliably supported POST.

I dimly recall a pre-form web, but it could easily be they just took over a little-used Berners-Lee verb. (For instance, PUT support was atrocious for a while.)

This is not about pre-form web. It's about pre-CORS web. Which is pretty recent web. CORS was "widely & properly" supported by "recently released" browsers around 2012-2013. Of course it's only as of very recently that you could safely assume 2010-2013 browser versions were completely out of circulation.

My bad; hadn't parent'ed enough, and the "using different methods than GET" clarification would not have been anachronistic even in the previous century.

PUT can still be weird. For example, PHP doesn't process multipart/form-data if it's a PUT instead of a POST, I'm working on an API in Laravel and for methods that need to PUT a file I have to use Laravel's _method spoofing.

In a cross-domain context, when you are expecting the browser to make its XHR for JSON data via JavaScript to a third-party API. Think about making a call to the Flickr.com HTTP API from your own WordPress myblog.com domain. In that context, the XHRs didn't support POST/PUT. Remember, even the fetch() API is pretty recent. POST-based forms are irrelevant for API usage.

This MDN doc covers some of the complexity:

https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

And here is when browsers added support for CORS:

https://caniuse.com/#feat=cors

Agreed about the idempotency concern. Safari for example will sometimes make past GET requests while making a current GET request, so you can get oopsied if you put a non-idempotent request in a GET.

On the other hand, if multi submitting causes bad behavior, a failsafe should probably be baked in to the endpoint logic itself rather than relying on POST not being abused.

I got to take a course on API Design with Joshua Bloch and Charlie Garrod (CMU's 17-480) in the spring. While I don't think the course content is available online, there's a good amount of tactical advice that goes with the talk [1]. The most memorable things to me were an emphasis on user testing to validate your design - we would draft APIs and then interview people and make them try to write code with them; and being willing to go back to the drawing board to change things if necessary. I think these are common ideas in (visual) user interface design, but for some reason are overlooked in coding.

There was an anecdote about how the creator of the Makefile (Stuart Feldman) originally hacked together the implementation so that tabs were required for each command (rather than spaces), and didn't want to change it because dozens of people were already relying on that behavior at this point... [2] seems to confirm this.

[1] http://fwdinnovations.net/whitepaper/APIDesign.pdf

[2] https://beebo.org/haycorn/2015-04-20_tabs-and-makefiles.html

Do you have any tips on how someone can craft persuasive arguments which lead a manager or their team to start seeing API design as valuable?

Really need to couch in terms of "value" to the individuals and org - point to bugs/regressions caused by loose interfaces, copy pasted code, able to use cool tools if you follow REST, JSON-API, GraphQL, etc.

Most folks seem totally unpersuaded by "maybe one day 3d parties will use this API!" hypotheticals.

The hard part about this is learning what individuals and organisations find valuable.

It really depends. Who is the API for?

I agree with the sibling comment that showing concrete failures that were caused by or contributed to by poor API design is effective.

If it's a public (customer-facing) API, perhaps you can compare your version to a competitor's: to achieve the same task, what needs to be done?

Internally... I haven't had a lot of luck here. Push for it in code/design reviews and sneak a refactor into your PRs? One thing that helps is to have ready examples, so you can say "Hey, I think we need a higher level abstraction here or else we'll be copy-pasting around the same 12 calls every time we want to X, just like we already do with Y API." and your teammates hopefully recognize that pain.

Thanks for the link. You might want to fix the missing 'of' in the first paragraph:

This page describes some the principles behind the design of the API.

Will fix! How embarrassing, I think this page has had that typo on it for like 8 years :)

I dunno how much I'd trust a Google speech about api design. Few of their API follow the same rules and most are horrendous to work with. It's the wildwest over there.

A Josh Bloch talk is not a "Google speech"

My bad, I misread, it was given at Google. Guess their engineers didn't listen. :x

Actually he was employed by Google when he gave that speech at Google.... So I'd call it a Google speech.

I presume you are a bigger API design expert than Joshua Bloch. Please point us to your talk/insights.

Because public speech's make one an expert? How many Google api have you consumed, I'm guessing few, or you'd know what I'm talking about.

This talk looks to be a bit dated these days. I wish there were more alike with recent languages as well :-(

Reply on news.ycombinator.com