Designing irresistible apis
•Télécharger en tant que PPTX, PDF•
16 j'aime•2,445 vues
This is a newer, better ordered version of m previous presentation on this topi.
Recommandé
Contenu connexe
Tendances
Tendances (19)
En vedette
En vedette (20)
Similaire à Designing irresistible apis
Similaire à Designing irresistible apis (20)
Plus de Kirsten Hunter
Plus de Kirsten Hunter (20)
Dernier
Dernier (20)
Designing irresistible apis
- 16. Photo by superhappybe - Creative Commons Attribution License http://www.flickr.com/photos/78593417@N06 Created with Haiku Deck
- 17. Photo by Kalexanderson - Creative Commons Attribution-NonCommercial-ShareAlike License http://www.flickr.com/photos/45940879@N04 Created with Haiku Deck
- 18. Photo by K J Payne - Creative Commons Attribution-ShareAlike License http://www.flickr.com/photos/34209858@N07 Created with Haiku Deck
- 19. Photo by gritts1 - Creative Commons Attribution-NonCommercial-ShareAlike License http://www.flickr.com/photos/72425002@N00 Created with Haiku Deck
- 20. Photo by Jsome1 - Creative Commons Attribution License http://www.flickr.com/photos/40145521@N00 Created with Haiku Deck
- 21. Photo by Gatesee - Creative Commons Attribution-NonCommercial License http://www.flickr.com/photos/17919943@N02 Created with Haiku Deck
- 22. Photo by pixelblume - Creative Commons Attribution-NonCommercial-ShareAlike License http://www.flickr.com/photos/65581677@N06 Created with Haiku Deck
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.
- 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: 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.
- 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!!!