Intuitive APIs and Developer Education
0 likes1,032 views
The document discusses the history and design of APIs, beginning with the establishment of REST principles to provide consistency across APIs. It describes how early APIs like eBay and Flickr implemented REST and provided documentation and tools to help developers. Later sections discuss the development of OAuth to allow third-party access to data without sharing credentials, and concepts like Open Graph that allowed representing web content in a social graph. The document emphasizes that contextual factors like the intended developers and their existing knowledge should inform how new APIs are designed and documented.
Intuitive APIs and Developer Education
- 2. Intuitive APIs and Developer Education Bear Douglas @beardigsit
- 3. Hi! I’m Bear. DevRel @ SlackHQ; formerly @Twitter, @FBPlatform, @Parse
- 4. What is Developer Relations, anyway?
- 5. ❏ Teach people how to use APIs ❏ Use a lot of APIs ourselves ❏ Develop strong opinions about API design ❏ Share those back with our product & engineering partners ❏ Learn a lot about how to explain abstract concepts to other engineers
- 6. Designing APIs that make sense
- 7. Designing APIs that make sense … because you want people to use them
- 8. Some history: REST (huge h/t to the team over at ReadMe) ● People wanted consistency in APIs ● Built for the web: ○ Uniform interface ○ Stateless ○ Client-server model ○ Cacheable
- 9. The name "Representational State Transfer" is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use. From Fielding’s dissertation publication: https://www.ics.uci.edu/~fielding/pubs/dissertation/evaluation.htm
- 10. From webarchive.org: developer.ebay.com, December 6, 2000
- 11. eBay’s API… ❏ Made REST more concrete (getItem example) ❏ Provided sample code ❏ Gave people an incentive to learn
- 12. From webarchive.org: flickr.com/services/api, August 31, 2006
- 13. From webarchive.org: flickr.com/services/api, August 31, 2006
- 15. Flickr developer tooling ● Reduce complexity ● Lower barriers to adoption ● Highlighted on the API site
- 16. Fast forward to 2010...
- 18. Open Graph Let developers represent their web apps and objects on the social graph
- 19. The Open Graph protocol enables any web page to become a rich object in a social graph. For instance, this is used on Facebook to allow any web page to have the same functionality as any other object on Facebook. Opening to the Open Graph Protocol: ogp.me
- 24. Open Graph Let developers represent their web apps and objects on the social graph … though what ended up being most meaningful were videos, music, articles, books, and profiles.
- 25. … and it paved the way for GraphQL Facebook and objects within it provided a concrete representation of graph data
- 27. … but let’s go back to Flickr
- 29. OAuth Get permission to access data as a third party, without sharing credentials
- 30. In order for the client to access resources, it first has to obtain permission from the resource owner. This permission is expressed in the form of a token and matching shared-secret. The purpose of the token is to make it unnecessary for the resource owner to share its credentials with the client. Unlike the resource owner credentials, tokens can be issued with a restricted scope and limited lifetime, and revoked independently. From the OAuth 1.0 spec: https://tools.ietf.org/html/rfc5849
- 32. OAuth in the Enterprise: the case for “Workspace Apps”
- 33. ❏ (Mostly) familiar concepts around auth ❏ Lots of platform-specific abstract concepts: workspaces, orgs, resources, channel membership ❏ Did support with tooling ❏ Did rewrite documentation ❏ Few incentives to rewrite
- 34. Context matters when you decide whether to teach developers something new or use what they know
- 35. Who are my developers? What might they already know and expect?
- 36. When might they give up? How could we convince them to keep trying?
- 37. Thanks!