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.

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

31. Image: dummies.com/business/marketing/social-media-marketing/how-to-use-twitter-to-share-blog-content

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!