The document discusses different approaches to API design taken by Socialtext, Netflix, and LinkedIn. Socialtext uses a simple RESTful design focused on usability. Netflix's API provides more data through expansion and hyperlinks to reduce calls. LinkedIn has a powerful query language that allows developers to specify exactly what data they need from the deeply interlinked social network graph. The key is designing APIs based on the unique nature of the data and use cases while balancing flexibility, control, and developer experience.
2. Building a resource map
Usability concerns
Interface design choices
Examples: Socialtext, Netflix, LinkedIn
Kirsten Jones http://www.princesspolymath.com @synedra
3. APIs must be usable
Consistency
How do you want applications to behave?
What makes sense for your data?
Reduce errors, increase success
Kirsten Jones http://www.princesspolymath.com @synedra
4. Resource map
Support reasonable cross-referenced
resources
Expandability of resources
Explicit declaration of resource structure
Hyperlinking related resources
Kirsten Jones http://www.princesspolymath.com @synedra
5. Cover three different APIs with different
approaches
Describe the schema for the API
Describe interface choices made
Pros/Cons of approach
Kirsten Jones http://www.princesspolymath.com @synedra
6. Socialtext
Simple wiki API, very basic implementation
Netflix
More complicated data space
Some expansion to reduce calls
Related resource hyperlinks
LinkedIn
Much more complicated
Powerful query language
Kirsten Jones http://www.princesspolymath.com @synedra
7. Basic wiki software
Users, workspaces, pages – now signals and
themes
REST API designed 7 years ago for 3rd parties
and to run site widgets
Design considerations – consistency,
usability, simplicity
Kirsten Jones http://www.princesspolymath.com @synedra
8. All resources under /data
Collections
/nouns gives a list of resource type ‘noun’
▪ Ex: /data/workspaces
Entities
/nouns/nounid gives a resource
▪ Ex: /data/workspaces/12
Sorting, filtering, ordering with parameters
Kirsten Jones http://www.princesspolymath.com @synedra
9. Limiting scope for this discussion
Workspaces, pages, tags
/data/workspaces
/data/workspaces/:wsid
/data/workspaces/:wsid/pages
/data/workspaces/:wsid/pages/:pageid
/data/workspaces/:wsid/pages/:pageid/tags
/data/workspaces/:wsid/tags/:tagid/pages
Kirsten Jones http://www.princesspolymath.com @synedra
10. Pros
Consistent mapping of (fairly simple) domain
Can reach resources multiple ways
Browsable API allows for discoverability
Cons
Requires many more calls
No URL links to related resources
Kirsten Jones http://www.princesspolymath.com @synedra
11. Movie catalog information
Movies and people associated with them
Access to user queues and recommendations
Information about user’s relationship to
movie (watched, rated)
Kirsten Jones http://www.princesspolymath.com @synedra
12. Devices (Xbox, TVs)
Third party developers
Minimize traffic for heavy users
Monetized use cases well understood
Filtering, ordering, searching
Kirsten Jones http://www.princesspolymath.com @synedra
14. List context
Returned for searches, lists, recommendations,
similar movies
minimal info – id, box art, release year, name,
rating
Hyperlinks to related entities
Expansion available to get more info
Details context
All available title information
Kirsten Jones http://www.princesspolymath.com @synedra
17. Used for related information
Can be used to inform ‘expand’ choices
Can be used to pull additional resources
Prevent developer mistakes (manually
creating resource URL)
Kirsten Jones http://www.princesspolymath.com @synedra
18. Search
/catalog/titles?term=cruise
Autocomplete
Very fast responses
Even more limited data (name, ID)
/catalog/titles/autocomplete?term=Snakes
Expand
Allows applications to retrieve details in list
/catalog/?term=cruise&expand=cast,directors
Kirsten Jones http://www.princesspolymath.com @synedra
19. Pros
Great for very specific use cases (devices)
Provides URLs as identifiers and hyperlinks
Some expansion to prevent spamming
Cons
Not fantastic for exploration/innovation
No way to reduce information retrieved
No way to dig deeper into tree
Kirsten Jones http://www.princesspolymath.com @synedra
20. Social Network
Deeply Interlinked
Rich Information
Many potential use cases
Kirsten Jones http://www.princesspolymath.com @synedra
21. Support many use cases
Provide control over response size
Limit overall call volume
Exercise consistency
Kirsten Jones http://www.princesspolymath.com @synedra
22. /people
Mother of all resources (to excess)
Contains expandable information about profile
data
/groups
/companies
/jobs
Each has the ability to expand to include
information about other top level resources
Kirsten Jones http://www.princesspolymath.com @synedra
23. No hyperlinks
Being able to drill down makes this less of an issue
Throttles
Everybody wants user databases – fraud
Very expressive query language
Developers get exactly the response they need
LinkedIn can analyze queries to optimize
Reduces number of queries
Kirsten Jones http://www.princesspolymath.com @synedra
24. Not very RESTful, but highly effective
Allows developers to specify exactly what
data they want, and drill down
All the user’s connections, the schools they went
to, their company name and company’s industry
Specifying fields means only the data you want –
the default is not guaranteed to be consistent
Kirsten Jones http://www.princesspolymath.com @synedra
25. /people/~
User’s default profile
Usually id, first name, last name, headline
/people/~:(id, first-name,last-name,headline)
Same request, guaranteed to have the right info
/people/~:(id,first-name,picture-profile-
url,educations:(school-
name),positions:(company:(name)))
Kirsten Jones http://www.princesspolymath.com @synedra
27. Facets allow flexible control of queries
Can be returned for a user’s network
What are the top 10 industries in the network?
Used to limit list results
Tell me all the connections who went to UCSC
Facets allow applications to provide
exploration or customize experience
Kirsten Jones http://www.princesspolymath.com @synedra
28. Pros
Powerful and flexible
Reduces number of calls
Allows for strict throttles
Cons
Steep learning curve
Calls to the backend can be expensive (calling
multiple resources)
Kirsten Jones http://www.princesspolymath.com @synedra
29. Your data is unique – schema should reflect
that
Don’t limit developers accidentally
Default/expand is great for very specific use
cases
To encourage innovation in a more graph-like
system, allow developers to express what
they want
Facets, fields, drill down
Kirsten Jones http://www.princesspolymath.com @synedra