News for hackers. Stuff that matters.
Re:Ask HN: Suggestions for books about API design? by pixelmonkey on Saturday September 05, 2020 @10:29AM (#24383790)
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

Re:Ask HN: Suggestions for books about API design? by dullgiulio on Saturday September 05, 2020 @11:30AM (#24384282)
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.

Re:Ask HN: Suggestions for books about API design? by pixelmonkey on Saturday September 05, 2020 @11:34AM (#24384309)
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.
Re:Ask HN: Suggestions for books about API design? by pvg on Saturday September 05, 2020 @11:42AM (#24384361)
I don't think there's ever been a time browsers haven't reliably supported POST.
Re:Ask HN: Suggestions for books about API design? by pixelmonkey on Saturday September 05, 2020 @12:46PM (#24384922)
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

Re:Ask HN: Suggestions for books about API design? by 082349872349872 on Saturday September 05, 2020 @12:36PM (#24384848)
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.)
Re:Ask HN: Suggestions for books about API design? by pixelmonkey on Saturday September 05, 2020 @12:55PM (#24384988)
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.
Re:Ask HN: Suggestions for books about API design? by 082349872349872 on Saturday September 05, 2020 @01:05PM (#24385082)
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.
Re:Ask HN: Suggestions for books about API design? by karlshea on Saturday September 05, 2020 @01:49PM (#24385445)
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.
Re:Ask HN: Suggestions for books about API design? by alezha on Saturday September 05, 2020 @10:50PM (#24388587)
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.

Re:Ask HN: Suggestions for books about API design? by bobbiechen on Saturday September 05, 2020 @09:38PM (#24388300)
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

Re:Ask HN: Suggestions for books about API design? by afarrell on Saturday September 05, 2020 @10:33PM (#24388529)
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?
Re:Ask HN: Suggestions for books about API design? by gedy on Saturday September 05, 2020 @11:05PM (#24388645)
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.

Re:Ask HN: Suggestions for books about API design? by afarrell on Monday September 07, 2020 @05:22PM (#24403035)
The hard part about this is learning what individuals and organisations find valuable.
Re:Ask HN: Suggestions for books about API design? by bobbiechen on Sunday September 06, 2020 @11:05AM (#24391811)
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.

Re:Ask HN: Suggestions for books about API design? by grey-area on Saturday September 05, 2020 @02:06PM (#24385569)
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.

Re:Ask HN: Suggestions for books about API design? by pixelmonkey on Saturday September 05, 2020 @02:38PM (#24385826)
Will fix! How embarrassing, I think this page has had that typo on it for like 8 years :)
Re:Ask HN: Suggestions for books about API design? by mtnGoat on Saturday September 05, 2020 @04:43PM (#24386713)
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.
Re:Ask HN: Suggestions for books about API design? by tsycho on Saturday September 05, 2020 @07:13PM (#24387600)
I presume you are a bigger API design expert than Joshua Bloch. Please point us to your talk/insights.
Re:Ask HN: Suggestions for books about API design? by mtnGoat on Monday September 07, 2020 @10:52AM (#24399805)
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.
Re:Ask HN: Suggestions for books about API design? by neonate on Saturday September 05, 2020 @04:47PM (#24386734)
A Josh Bloch talk is not a "Google speech"
Re:Ask HN: Suggestions for books about API design? by mtnGoat on Saturday September 05, 2020 @04:52PM (#24386761)
Actually he was employed by Google when he gave that speech at Google.... So I'd call it a Google speech.
Re:Ask HN: Suggestions for books about API design? by mtnGoat on Saturday September 05, 2020 @04:51PM (#24386758)
My bad, I misread, it was given at Google. Guess their engineers didn't listen. :x
Re:Ask HN: Suggestions for books about API design? by bitL on Saturday September 05, 2020 @08:20PM (#24387887)
This talk looks to be a bit dated these days. I wish there were more alike with recent languages as well :-(