Rest schema design

Kirsten Jones, Technical Leader, Cisco Systems

@synedra
http://www.princesspolymath.com

 Building a resource map
 Usability concerns
 Interface design choices
 Examples: Socialtext, Netflix, LinkedIn

Kirsten Jones http://www.princesspolymath.com @synedra

 APIs must be usable
 Consistency
 How do you want applications to behave?
 What makes sense for your data?
 Reduce errors, increase success


 Resource map
 Support reasonable cross-referenced
resources
 Expandability of resources
 Explicit declaration of resource structure
 Hyperlinking related resources


 Cover three different APIs with different
approaches
 Describe the schema for the API
 Describe interface choices made
 Pros/Cons of approach


 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


 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


 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


 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


 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


 Movie catalog information
 Movies and people associated with them
 Access to user queues and recommendations
 Information about user’s relationship to
movie (watched, rated)


 Devices (Xbox, TVs)
 Third party developers
 Minimize traffic for heavy users
 Monetized use cases well understood
 Filtering, ordering, searching


 /catalog/titles
 Movies, TV shows
 /catalog/people
 Actors, directors
 /users
 Queue management, recommendations


 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

<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>


 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)


 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


 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


 Social Network
 Deeply Interlinked
 Rich Information
 Many potential use cases


 Support many use cases
 Provide control over response size
 Limit overall call volume
 Exercise consistency


 /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

 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


 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


 /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)))


 /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


 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


 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)


 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

 https://www.socialtext.net/st-rest-docs/
 http://developer.netflix.com
 http://developer.linkedin.com

 http://www.princesspolymath.com

 http://www.restfest.org/

Questions?

Rest schema design

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (7)

Destacado

Destacado (9)

Similar a Rest schema design

Similar a Rest schema design (20)

Más de Kirsten Hunter

Más de Kirsten Hunter (20)

Último

Último (20)

Rest schema design