Rest schema design

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,

LinkedIn

http://www.princesspolymath.com/


Driving principles

APIs must be usable Consistency How do you want applications to

behave? What makes sense for your data? Reduce errors, increase success



Considerations

Resource map Support reasonable cross-referenced

resources Expandability of resources Explicit declaration of resource

structure Hyperlinking related resources



Tour schedule

Cover three different APIs with different approaches

Describe the schema for the API Describe interface choices made Pros/Cons of approach



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



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



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



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



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



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)



Considerations

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



Resource Map

/catalog/titles Movies, TV shows

/catalog/people Actors, directors

/users Queue management, recommendations



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



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>



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>



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)



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



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



LinkedIn’s Data

Social Network Deeply Interlinked Rich Information Many potential use cases



Considerations

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



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



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



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



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



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



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



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)



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



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?


http://developer.netflix.com/



http://developer.linkedin.com/


http://www.restfest.org/

Rest schema design

Technology

Transcript of Rest schema design