4 ms·

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

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=19 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 https://www.parse.ly/help/api/restful-apis

dullgiulio 6y ago
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.
- pixelmonkey 6y ago
  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.
  - pvg 6y ago
    I don't think there's ever been a time browsers haven't reliably supported POST.
    - 082349872349872 6y ago
      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.)
      - pixelmonkey 6y ago
        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.
        082349872349872 6y ago
        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.
      - karlshea 6y ago
        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.
    - pixelmonkey 6y ago
      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 https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS And here is when browsers added support for CORS: https://caniuse.com/#feat=cors https://caniuse.com/#feat=cors
- alezha 6y ago
  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.
grey-area 6y ago
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.
- pixelmonkey 6y ago
  Will fix! How embarrassing, I think this page has had that typo on it for like 8 years :)
mtnGoat 6y ago
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.
- neonate 6y ago
  A Josh Bloch talk is not a "Google speech"
  - mtnGoat 6y ago
    My bad, I misread, it was given at Google. Guess their engineers didn't listen. :x
  - mtnGoat 6y ago
    Actually he was employed by Google when he gave that speech at Google.... So I'd call it a Google speech.
- tsycho 6y ago
  I presume you are a bigger API design expert than Joshua Bloch. Please point us to your talk/insights.
  - mtnGoat 6y ago
    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.
bitL 6y ago
This talk looks to be a bit dated these days. I wish there were more alike with recent languages as well :-(
bobbiechen 6y ago
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 http://fwdinnovations.net/whitepaper/APIDesign.pdf [2] https://beebo.org/haycorn/2015-04-20_tabs-and-makefiles.html https://beebo.org/haycorn/2015-04-20_tabs-and-makefiles.html
- afarrell 6y ago
  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?
  - gedy 6y ago
    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.
    - afarrell 6y ago
      The hard part about this is learning what individuals and organisations find valuable.
  - bobbiechen 6y ago
    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.

dullgiulio 6y ago

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.

pixelmonkey 6y ago
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.
- pvg 6y ago
  I don't think there's ever been a time browsers haven't reliably supported POST.
  - 082349872349872 6y ago
    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.)
    - pixelmonkey 6y ago
      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.
      - 082349872349872 6y ago
        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.
    - karlshea 6y ago
      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.
  - pixelmonkey 6y ago
    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 https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS And here is when browsers added support for CORS: https://caniuse.com/#feat=cors https://caniuse.com/#feat=cors
alezha 6y ago
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.

grey-area 6y ago

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.

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

mtnGoat 6y ago

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.

neonate 6y ago
A Josh Bloch talk is not a "Google speech"
- mtnGoat 6y ago
  My bad, I misread, it was given at Google. Guess their engineers didn't listen. :x
- mtnGoat 6y ago
  Actually he was employed by Google when he gave that speech at Google.... So I'd call it a Google speech.
tsycho 6y ago
I presume you are a bigger API design expert than Joshua Bloch. Please point us to your talk/insights.
- mtnGoat 6y ago
  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.

bitL 6y ago

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

bobbiechen 6y ago

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 http://fwdinnovations.net/whitepaper/APIDesign.pdf [2] https://beebo.org/haycorn/2015-04-20_tabs-and-makefiles.html https://beebo.org/haycorn/2015-04-20_tabs-and-makefiles.html

afarrell 6y ago
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?
- gedy 6y ago
  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.
  - afarrell 6y ago
    The hard part about this is learning what individuals and organisations find valuable.
- bobbiechen 6y ago
  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.