3 ms·

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 onli

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.

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.