Pro Yearly is on sale from $80 to $50! »

Skeleton-free Closets: Designing internal APIs you can be proud of

Skeleton-free Closets: Designing internal APIs you can be proud of

by Matthew McClure @ APIStrat 2014 in Chicago

Transcript

  1. SKELETON FREE CLOSETS DESIGNING INTERNAL APIS YOU CAN BE PROUD

    OF API STRATEGY & PRACTICE: CHICAGO, 2014  @matt_mcclure
  2. None
  3. THE RISE OF THE INTERNAL API 

  4. THEN: THE MONOLITH  One application to rule them all.

  5. NOW: MICROSERVICES  A suite of small services that communicate.

  6.    (Or at least somewhere in between)

  7. WHICH IS COOL! BUT...

  8. THE  TRUTH

  9. MOST* INTERNAL APIS SUCK *Based on a highly scientific sampling

    of my friends and colleagues
  10. BUT WHY?

  11. NOBODY  THEM

  12. WHAT SEEMS TO HAPPEN 1. There are two services (or

    an application is broken up) 2. Need to glue these things together 3. Slap together an API interface 4. Functional? Done. 5. 
  13. [ACTUAL] EXAMPLE INTERACTION Me: “Do you have any examples of

    a bad internal API?” Colleague: “Well, the other day I saw...” Me: “Perfect. Can you link me to the docs?” Colleague: *blank stare* Colleague: *laughter*
  14. SO HOW CAN WE DO BETTER?

  15. DESIGN FIRST Every. Single. Time.

  16. BUT WHAT ABOUT... NO.

  17. TOO MANY  FOR EXCUSES ...or any text editor of

    your choice.
  18. GET COLLEAGUES INVOLVED Show design drafts to people who will

    have to use it
  19. IT TAKES AN ORGANIZATION Get * management involved as well

  20. KICK BAD HABITS Your org is probably building bad internal

    APIs because it's a habit now.
  21. KILL YOUR DARLINGS It's good to have organization guidelines and

    all, but...
  22. DON'T CLING FOR CONSISTENCY SAKE If patterns / best practices

    / dev preferences change enough, change with them
  23. AIM FOR IDIOMATIC Internal APIs should feel "standard" within the

    broader context
  24. DOCUMENT EVERYTHING Even Especially if you're not proud of it.

  25. OWN UP TO SHORTCOMINGS Surprises are worse than idiosyncracies

  26. KEEP IT UP TO DATE This is harder than it

    seems. Admit it.
  27. BE A GOOD CITIZEN Update documentation when you notice problems.

  28. TL;DR INTERNAL != CUT CORNERS

  29. THINK ABOUT FUTURE YOUS  These APIs will potentially be

    a communication layer for years.
  30. THANK YOU   mmcclure@brightcove.com  @matt_mcclure