Successfully reported this slideshow.

Designing irresistible apis



Upcoming SlideShare
Designing irresistible APIs
Designing irresistible APIs
Loading in …3
1 of 23
1 of 23

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

Related Audiobooks

Free with a 14 day trial from Scribd

See all

Designing irresistible apis

  1. 1. @synedra - #FILive
  2. 2. @synedra - #FILive
  3. 3. @synedra - #FILive
  4. 4. @synedra - #FILive
  5. 5. @synedra - #FILive
  6. 6. @synedra - #FILive
  7. 7. @synedra - #FILive
  8. 8. @synedra - #FILive
  9. 9. @synedra - #FILive
  10. 10. @synedra - #FILive
  11. 11. @synedra - #FILive
  12. 12. @synedra - #FILive
  13. 13. @synedra - #FILive
  14. 14. @synedra - #FILive
  15. 15. @synedra - #FILive
  16. 16. Photo by superhappybe - Creative Commons Attribution License Created with Haiku Deck
  17. 17. Photo by Kalexanderson - Creative Commons Attribution-NonCommercial-ShareAlike License Created with Haiku Deck
  18. 18. Photo by K J Payne - Creative Commons Attribution-ShareAlike License Created with Haiku Deck
  19. 19. Photo by gritts1 - Creative Commons Attribution-NonCommercial-ShareAlike License Created with Haiku Deck
  20. 20. Photo by Jsome1 - Creative Commons Attribution License Created with Haiku Deck
  21. 21. Photo by Gatesee - Creative Commons Attribution-NonCommercial License Created with Haiku Deck
  22. 22. Photo by pixelblume - Creative Commons Attribution-NonCommercial-ShareAlike License Created with Haiku Deck
  23. 23. @synedra - #FILive

Editor's Notes

  • I’ve been working with APIs (and the developers who use them) for almost 10 years
    I currently work as Akamai as part of their Open team. Previously I worked at Socialtext, Netflix, LinkedIn, and learned a lot about stumbling blocks for developers.
    My goal in life is to reduce the amount of frustration in the world, and this is an area that’s full of opportunities for improvement.
    I wander the world, like Caine in Kung Fu, teaching companies to make APIs that don’t make developers cry, and teaching developers how to use APIs without crying.
    Important note about this presentation: I’m going to talk only briefly about architecture and creating a schema. Irresistible APIs can have any one of the available architectures and pretty much any schema as long as you follow the points I make. This will make sense as you go along. Also, this presentation applies to open, external APIs as well as internal, private ones.

    This presentation is fairly high level, and designed to be useful to developers, product managers, designers and even executive management types!
  • Here they are! Notes!

    If you have questions ask me at @synedra (or, but that doesn’t help my Klout score!)

    My website is, where you can find blog posts with more links on these topics.

    I don’t have code on my slides, but I do have a github repository as synedra as well.
  • Most often APIs are created “Because… API!!!” But no. That approach is generally doomed to fail. Here’s some examples of answers to this question which are more compelling.
  • First class.
    What is *your* business value?
    What use cases are validfor you?
    The API needs to make these things easy, use the use cases to drive development and create tutorials
    Your developers are your partners. Communicate with them, support them, help them be successful. No silo’d information.

    Currently many, many companies have APIs as requirements for their developers, with no guidance as to the end user goals. What we end up with looks like…
  • The potato you left in the garage for too long. Unrelated APIs, growing in all directions. Duplicated code from the main product/website and even among APIs that are doing similar functions.
  • Netflix has the most amazing market penetration of any streaming video provider. Any video system you buy (TV, DVD player, Roku, or even tablets/mobile devices) have Netflix available. Sure, some of them have other providers but Netflix is the defacto standard, because they got there first and they push very hard to maintain that status.
  • What is your business value? Think back to the business cases and technical cases. Monetization is rarely a reasonable goal for an API, but partner integration (even integration with other internal teams) is a perfectly valid and strong business case.
  • How are you going to measure success? Usage, new users, activity? Consider that moving people from (resource intensive) web forms to (automatable and less resource intensive) APIs can be a great measure of API success.
  • Now that you know what you want to get from your API, build use cases. Mobile, integration, reporting… figure out what should be easy with your API. As you design your schema, make sure that you’re supporting these use cases.

    Strong note – mobile developers expect, want, even need to be able to make a single call per screen. This frequently requires that you allow for expansion, combination, or some other non-RESTful affordances. Remember, an API must be designed to make the use cases you’re targeting easy.
  • Twitter, Facebook, and Linkedin are all social networks that survive based on the constant activity and “touch” of their users. Encouraging developers to integrate, and encouraging users to use those integrations, are critical to maintaining their market share.
  • This is easily the strongest argument for having a good, strong, reliable API. If your partners integrate your system with their systems, there will be a lot of friction discouraging them from switching to a new partner. You need to understand what’s important to your partners and support their needs, but once you do that they’re much more likely to stick with you.
  • When designing an API, architectural considerations are frequently the only things considered as important topics. They’re important, yes, but not as important as some other items. Nonetheless, you should put some thought into these as you design your API.
  • “An affordance is a quality of an object, or an environment, which allows a user to perform an action.” What can/should users be able to do on your system?
  • The schema is frequently considered to be the main design decision in building an API. How you organize your resources, whether you provide expansion or other query language for developers to customize the results they get – these are all important choices, but need to be driven by use cases, not designed in a vacuum.

    Modeling your schema once you know what you want your API to do and how you want people to use it is a great exercise – check out RAML, blueprint, and swagger for frameworks to do this.

    Nonetheless, here’s a link to an interesting discussion of this topic:
  • Authentication: Who am I? (Drivers license, Username/password)
    In the web world, two common authentication schemes are Oauth ( and 2-factor authentication (
    Authorization: What can I do? (Buy alcohol, administer a site)
    Remember that these are different things! Don’t conflate them.
    Once you know who is doing what, including what application/user combination is doing things. Great for measurements, analytics, and driving future features/development of your product.

    Additionally, you can use authorization in combination with rate limiting and throttling, based on your relationship with the application provider.
  • This is arguably the most important contributor to the success of your API, whether it’s an open API or an internal-only API. Check out Twitter’s developer portal, or Twilio’s, to get an idea of how the best developer experience looks with onboarding, tutorials, example code and documentation.
  • You’ve got your business value, your metrics, and your use cases. Communicating this to your developer partners (all customers of your API are partners, whether internal, external, or business partners) helps them understand why you have an API.
  • Once you’ve communicated your reasons for having an API to your developers, they’re much more likely to trust that your API is safe for them to base their own products on.
  • Marketing to developers is not like marketing to regular people. Play with them, give them building blocks. Give them the gaming experience of “leveling up” through small tutorials, rather than having an exhausting and demoralizing 17 page single tutorial.
  • Encourage your users to explore your API using tools like IOTools, and help them to learn how to use HTTP sniffers to watch the traffic and understand what’s going wrong when debugging.
  • Teach your developers how to ask questions so you can answer them the first time, rather than exacerbating their frustration by iterating numerous times.

    I did X. I expected Y to happen. To my dismay, Z happened instead.

    I jumped off a cliff. I expected to sprout wings and fly. To my dismay, I plunged to my death instead.

    All 3 are critical pieces of information. If their expectation is incorrect, then it’s still a support issue – your documentation should have told them what was going to happen. If it’s a bug, say so and open a ticket.
  • I don’t like ‘em.

    If you need an SDK for your API, it’s not easy enough. Third party libraries are fine, example code is critical, but if you have SDK’s for multiple languages you’re incurring a huge technical debt whenever you change your API, you’re making it harder to debug user problems (is it the SDK or the API) and you’re preventing your users from understanding exactly how your API works.

    HTTP is easy. Don’t overcomplicate your life by creating unnecessary crutches ☺
  • All intelligent discourse on the internet ends as soon as a cat picture is posted. So here’s mine!

    Questions to or @synedra.

    Check out the API Codex for more info on APIs (

    And go out there and have fun!!!
  • ×