REST API Design Kirsten Jones, Technical Leader, Cisco Systems @synedra http:// www.princesspolymath.com
May 08, 2015
REST API DesignKirsten Jones, Technical Leader, Cisco Systems
@synedrahttp://www.princesspolymath.com
Kirsten Jones http://www.princesspolymath.com @synedra
Overview
Building a resource map Usability concerns Interface design choices Examples: Socialtext, Netflix,
Kirsten Jones http://www.princesspolymath.com @synedra
Driving principles
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
Considerations
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
Tour schedule
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
Example APIs
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
Socialtext
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
Socialtext REST API Conventions
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
Socialtext Resource Map
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
Pros / Cons
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
Netflix’s Data
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
Considerations
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
Resource Map
/catalog/titles Movies, TV shows
/catalog/people Actors, directors
/users Queue management, recommendations
Kirsten Jones http://www.princesspolymath.com @synedra
Netflix title resource
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
Example response
<catalog_title> <id>http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522 </id> <title short="The Office: Season 1" regular="The Office: Season 1"/> <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70023522.jpg"
medium="http://alien2.netflix.com/us/boxshots/small/70023522.jpg"
large="http://alien2.netflix.com/us/boxshots/large/70023522.jpg"/> <link href= "http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522/synopsis" rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"/> <release_year>2005</release_year> <category scheme="http://api-public.netflix.com/categories/tv_ratings" label="TV-14"/> <runtime>8700</runtime>…</catalog_title>
Kirsten Jones http://www.princesspolymath.com @synedra
Hyperlinks and Schema
<catalog_title> <id>http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522 </id> <title short="The Office: Season 1" regular="The Office: Season 1"/> <box_art small="http://alien2.netflix.com/us/boxshots/tiny/70023522.jpg"
medium="http://alien2.netflix.com/us/boxshots/small/70023522.jpg"
large="http://alien2.netflix.com/us/boxshots/large/70023522.jpg"/> <link href= "http://api-public.netflix.com/catalog/titles/series/70023522/seasons/70023522/synopsis" rel="http://schemas.netflix.com/catalog/titles/synopsis" title="synopsis"/> <release_year>2005</release_year> <category scheme="http://api-public.netflix.com/categories/tv_ratings" label="TV-14"/> <runtime>8700</runtime>…</catalog_title>
Kirsten Jones http://www.princesspolymath.com @synedra
Hyperlinks
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
Netflix operators
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
Pros and Cons
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
LinkedIn’s Data
Social Network Deeply Interlinked Rich Information Many potential use cases
Kirsten Jones http://www.princesspolymath.com @synedra
Considerations
Support many use cases Provide control over response size Limit overall call volume Exercise consistency
Kirsten Jones http://www.princesspolymath.com @synedra
Resource map
/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
Choices
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
Query Language
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
Examples: Profiles
/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
Examples: Other Resources
/people/~/connections:(id,first-name,picture-profile-url,educations:(school-name),positions:(company:(name,industry)))
/people-search:(people:(id,first-name,last-name,picture-url,headline),num-results)?first-name=Clair
Kirsten Jones http://www.princesspolymath.com @synedra
Facets
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
Pros and Cons
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
Summary
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
Resources
https://www.socialtext.net/st-rest-docs/ http://developer.netflix.com http://developer.linkedin.com
http://www.princesspolymath.com
http://www.restfest.org/
Questions?