Why is an API like a puppy?

There are many answers but the essence of this presentation from #CraftConf 2015 is that puppies and APIs are long-term commitments that most of us aren't ready for until we can show that we have thought through all the implications.

Transcript

1. Why is an API like a puppy?
   Ade Oshineye
   

   View Slide

2. Who am I and why am I here?
   

   View Slide

3. Share what you learn
   This is Dave and I at PLOP 2005.
   We’re grateful to the people who shared what they’ve learned.
   That’s why I’m going to share some things I’ve learned today.
   

   View Slide

4. Who here has young children?
   Imagine I were to visit you and give your children a free puppy.
   What would happen?
   

   View Slide

5. Who wants a free puppy?
   

   View Slide

6. Free as in speech/beer/puppy
   Free as in beer/speech/puppy
   The worst kind of free.
   Overlooks the costs, responsibilities and consequences
   

   View Slide

7. Real puppies
   Public APIs are different
   Let’s talk about some common but incorrect beliefs that people hold about public APIs
   

   View Slide

8. Public API with real users doing
   business-valuable things in a
   competitive environment
   It also means that when I say API (in this presentation) I mean...
   

   View Slide

9. Public API with real users doing
   business-valuable things in a
   competitive environment
   It also means that when I say API (in this presentation) I mean...
   

   View Slide

10. Public API with real users doing
    business-valuable things in a
    competitive environment
    It also means that when I say API (in this presentation) I mean...
    

    View Slide

11. Public API with real users doing
    business-valuable things in a
    competitive environment
    It also means that when I say API (in this presentation) I mean...
    

    View Slide

12. Public API with real users doing
    business-valuable things in a
    competitive environment
    It also means that when I say API (in this presentation) I mean...
    

    View Slide

13. Do you work on a public API?
    

    View Slide

14. Experience comes from mistakes
    At Google we’ve been around long enough to have believed and regretted all of the following misconceptions
    

    View Slide

15. Common assumptions
    

    View Slide

16. API-first development
    

    View Slide

17. API-first development
    Everybody can use the same API
    

    View Slide

18. 1
    2
    3
    4
    Private API
    Consumer-facing UI
    Public API
    Ship it!
    Building a new feature
    First you build a private API then you build the consumer-facing product on top of it then you expose a public API that others can
    use and then you find out if it’s a good idea.
    

    View Slide

19. • Inappropriate API design
    • Inappropriate authentication model
    Costs and consequences
    

    View Slide

20. • Slower pace of development
    • Less flexibility
    Costs and consequences
    

    View Slide

21. APIs are free
    

    View Slide

22. APIs are free
    Development is the main cost
    

    View Slide

23. • Who writes your public documentation?
    • Who answers questions on Stack Overflow?
    • Who promotes your API?
    Costs and consequences
    

    View Slide

24. • Who prioritises and fixes API-specific bugs?
    • Who identifies and resolves API abuse/spam?
    Costs and consequences
    

    View Slide

25. API design is a solved problem
    “Just use ReST”
    Generic clients and HATEOAS will take care of the rest
    

    View Slide

26. API design is a solved problem
    Just use ReST
    “Just use ReST”
    Generic clients and HATEOAS will take care of the rest
    

    View Slide

27. • You find yourself saying HATEOAS to angry people and it doesn’t
    make them less angry about the lack of documentation
    • You discover that the ways people want to use your APIs don’t map
    cleanly to the collections of resources that you designed
    Costs and consequences
    

    View Slide

28. • You discover that you need client libraries for a variety of languages
    • You discover painful trade-offs involving API keys and OAuth
    Costs and consequences
    

    View Slide

29. “If you build it they will come”
    

    View Slide

30. “If you build it they will come”
    API quality determines success
    

    View Slide

31. ????
    This is a hackathon for Buzz in Stockholm in 2010. We did everything right from an API perspective but it wasn’t enough. We
    broke McKellar’s Law.
    

    View Slide

32. “A developer platform is only
    useful and interesting if it
    enhances something that’s already
    useful and is already used.”
    McKellar’s Law
    

    View Slide

33. Most successful public API at Google?
    What’s Google’s most commercially successful API?
    What technology does it use?
    

    View Slide

34. View Slide

35. Popularity means success
    

    View Slide

36. These APIs have something in common
    Twitter
    Snapchat
    Google Translate
    They became popular and then realised that wasn’t why they built an API
    

    View Slide

37. Twitter’s quadrants
    Twitter realised that they could only make money with advertising if they controlled the most popular clients
    

    View Slide

38. Snapchat’s ephemerality
    Snapchat realised that there were guarantees that only a trusted client could enforce
    

    View Slide

39. Google Translate and abuse
    Translate was sunset and then revived with a pricing plan because that’s the only way to control the kinds of abuse that happens
    with machine translation
    

    View Slide

40. How do I know if I'm ready for an
    API?
    

    View Slide

41. Short* answer:
    maturity
    This is why parents typically tell their children “when you’re older” rather than “you’re not mature enough”
    

    View Slide

42. The API has a good reason to
    exist
    Whatever benefit you get from the API is enough to justify all of the costs
    

    View Slide

43. You have a value exchange that
    works
    You know why your API is valuable
    You give something
    You get something
    Both sides are happy
    

    View Slide

44. It scales with traffic
    1 million QPD makes you happy
    1 billion QPD also makes you happy
    1 trillion QPD makes you even happier
    

    View Slide

45. It survives the passage of time
    It will still make sense in the future
    

    View Slide

46. You understand that public APIs
    have a lifecycle
    

    View Slide

47. Launch=>Versions=>Deprecation
    Ship V1.
    Ship new versions that break backwards compatibility.
    Shut down old versions.
    

    View Slide

48. You know how much your API will
    cost
    In terms of:
    - development
    -maintenance
    -support
    -staffing
    -opportunity cost for your core product
    

    View Slide

49. All aspects of the developer experience
    API Explorers to bug trackers
    

    View Slide

50. Do you have the right team?
    You understand all the aspects that need to exist for your team to succeed
    

    View Slide

51. Customers?
    You know who the potential customers and competitors are.
    You know how you will drive adoption of your API amongst those customers and in the face of competitive pressure
    

    View Slide

52. Competitors?
    You know who the potential customers and competitors are.
    You know how you will drive adoption of your API amongst those customers and in the face of competitive pressure
    

    View Slide

53. I’ve covered a lot of the pitfalls involved in launching a public API and hopefully it’s made you think twice. You now realise that
    the free puppy has hidden costs but my goal wasn’t to scare you away.
    

    View Slide

54. Personally I love APIs but I also know that...
    

    View Slide

55. APIs, like puppies, are an expensive
    long-term commitment...
    But sometimes they’re worth it.
    

    View Slide

56. View Slide