Designing irresistible APIs
•Télécharger en tant que PPTX, PDF•
4 j'aime•1,395 vues
This is my presentation on how to design APIs that developers love, that give your company good value, and that are successful in the long run. Since I use Haiku deck for my presentations, you should probably check the notes - without my interpretive dance it's the easiest way to understand what I'm talking about
Recommandé
Contenu connexe
Plus de Kirsten Hunter
Plus de Kirsten Hunter (20)
Designing irresistible APIs
- 1. @synedra - #FILive@synedra - #FILive
- 2. @synedra - #FILive@synedra - #FILive
- 3. @synedra - #FILive@synedra - #FILive
- 4. @synedra - #FILive@synedra - #FILive
- 5. @synedra - #FILive@synedra - #FILive
- 6. @synedra - #FILive@synedra - #FILive
- 7. @synedra - #FILive@synedra - #FILive
- 8. @synedra - #FILive@synedra - #FILive
- 9. @synedra - #FILive@synedra - #FILive
- 10. @synedra - #FILive@synedra - #FILive
- 11. @synedra - #FILive@synedra - #FILive
- 12. @synedra - #FILive@synedra - #FILive
- 13. @synedra - #FILive@synedra - #FILive
- 14. @synedra - #FILive@synedra - #FILive
- 15. @synedra - #FILive@synedra - #FILive
- 16. @synedra - #FILive@synedra - #FILive
- 17. @synedra - #FILive@synedra - #FILive
- 18. @synedra - #FILive@synedra - #FILive
- 19. @synedra - #FILive@synedra - #FILive
- 20. @synedra - #FILive@synedra - #FILive
- 21. @synedra - #FILive@synedra - #FILive
- 22. @synedra - #FILive@synedra - #FILive
- 23. Photo by Mr_H_1979 - Creative Commons Attribution License http://www.flickr.com/photos/36238220@N07 Created with Haiku Deck
- 24. Photo by superhappybe - Creative Commons Attribution License http://www.flickr.com/photos/78593417@N06 Created with Haiku Deck
- 25. Photo by Kalexanderson - Creative Commons Attribution-NonCommercial-ShareAlike License http://www.flickr.com/photos/45940879@N04 Created with Haiku Deck
- 26. Photo by K J Payne - Creative Commons Attribution-ShareAlike License http://www.flickr.com/photos/34209858@N07 Created with Haiku Deck
- 27. Photo by gritts1 - Creative Commons Attribution-NonCommercial-ShareAlike License http://www.flickr.com/photos/72425002@N00 Created with Haiku Deck
- 28. Photo by Jsome1 - Creative Commons Attribution License http://www.flickr.com/photos/40145521@N00 Created with Haiku Deck
- 29. Photo by Gatesee - Creative Commons Attribution-NonCommercial License http://www.flickr.com/photos/17919943@N02 Created with Haiku Deck
- 30. Photo by pixelblume - Creative Commons Attribution-NonCommercial-ShareAlike License http://www.flickr.com/photos/65581677@N06 Created with Haiku Deck
- 31. @synedra - #FILive@synedra - #FILive
Notes de l'éditeur
- 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 synedra@gmail.com, but that doesn’t help my Klout score!) My website is http://www.princesspolymath.com, 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.
- 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.
- 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.
- In the Non-API world, think of what happened with Amazon/Borders/Barnes and Noble. Amazon established themselves as the main book seller on the web, Barnes and Noble gave it a good shot (and have survived although been somewhat reduced) and Borders, who thought it was a fad, is gone completely. In the API world, Best Buy was one of the first brick and mortar based companies to have a strong API, and as a result they have survived, even thrived, in the new internet age. Circuit City didn’t get on board and that’s one of the reasons they died out.
- 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.
- Here are some technical use cases from companies who are largely funded via their API, by providing technical capabilities that are difficult without them.
- Integration with mail, producing emails that work well in every client and are robust and engaging, is very difficult. SendGrid simplifies this for companies.
- Just like sending emails can be complex, managing your email box can be overwhelming. Context.io allows you to take actions, organize your emails, generally create sanity in your inbox.
- Heroku and Amazon are companies who use metered usage to monetize their API. This is a great use case for companies providing hosting services who want to attract new companies/developers to ramp up their prototypes/alpha/beta versions start with small costs, and scale as needed until they are big enough to want to manage that service on their own.
- Twilio is a company who makes SMS and phone calls easy – they have a great developer experience and API integrations is the only way they make money. They’re quite successful with this strategy.
- 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: https://medium.com/@zwacky/design-a-beautiful-rest-api-901c73489458
- Authentication: Who am I? (Drivers license, Username/password) In the web world, two common authentication schemes are Oauth (oauth.org) and 2-factor authentication (http://en.wikipedia.org/wiki/Two-step_verification) Authorization: What can I do? (Buy alcohol, administer a site) Remember that these are different things! Don’t conflate them. Auditing 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.
- 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.
- Don’t tell me you can’t do this. Etsy did: http://www.slideshare.net/PaulWright9/apifirst-development-at-etsy-api-strategy-practice-ams-2014 API First allows you to avoid redundant code, improve agility, communication and collaboration across your company, and even, in the case of Etsy, improve products you’re not targeting. Whether you’re a tiny startup or an existing large company, this is worth serious consideration as a strategy to make your future development more successful.
- 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.
- 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.
- 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.
- Stand on the shoulders of giants. Find other APIs that provide similar functionality, and use those to inform your decisions. If another company provides something other than your core competency (such as identity management) consider using other companies’ APIs (such as twitter) to manage that functionality.
- 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 synedra@gmail.com or @synedra. Check out the API Codex for more info on APIs (http://apicodex.3scale.net) And go out there and have fun!!!