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, LinkedInKirsten 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 successKirsten Jones http://www.princesspolymath.com @synedra

 Resource map  Support reasonable cross-referenced resources  Expandability of resources  Explicit declaration of resource structure  Hyperlinking related resourcesKirsten Jones http://www.princesspolymath.com @synedra

 Cover three different APIs with different approaches  Describe the schema for the API  Describe interface choices made  Pros/Cons of approachKirsten Jones http://www.princesspolymath.com @synedra

 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 languageKirsten Jones http://www.princesspolymath.com @synedra

 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, simplicityKirsten Jones http://www.princesspolymath.com @synedra

 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 parametersKirsten Jones http://www.princesspolymath.com @synedra

 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/pagesKirsten Jones http://www.princesspolymath.com @synedra

 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 resourcesKirsten Jones http://www.princesspolymath.com @synedra

 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

 Devices (Xbox, TVs)  Third party developers  Minimize traffic for heavy users  Monetized use cases well understood  Filtering, ordering, searchingKirsten Jones http://www.princesspolymath.com @synedra

 /catalog/titles  Movies, TV shows  /catalog/people  Actors, directors  /users  Queue management, recommendationsKirsten Jones http://www.princesspolymath.com @synedra

 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 informationKirsten Jones http://www.princesspolymath.com @synedra

<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

 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

 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,directorsKirsten Jones http://www.princesspolymath.com @synedra

 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 treeKirsten Jones http://www.princesspolymath.com @synedra

 Social Network  Deeply Interlinked  Rich Information  Many potential use casesKirsten Jones http://www.princesspolymath.com @synedra

 Support many use cases  Provide control over response size  Limit overall call volume  Exercise consistencyKirsten Jones http://www.princesspolymath.com @synedra

 /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 resourcesKirsten Jones http://www.princesspolymath.com @synedra

 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 queriesKirsten Jones http://www.princesspolymath.com @synedra

 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 consistentKirsten Jones http://www.princesspolymath.com @synedra

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

 /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=ClairKirsten Jones http://www.princesspolymath.com @synedra

 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 experienceKirsten Jones http://www.princesspolymath.com @synedra

 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

 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 downKirsten Jones http://www.princesspolymath.com @synedra

 https://www.socialtext.net/st-rest-docs/  http://developer.netflix.com  http://developer.linkedin.com  http://www.princesspolymath.com  http://www.restfest.org/ Questions?Kirsten Jones http://www.princesspolymath.com @synedra

Rest schema design

by Kirsten Jones on Aug 07, 2012

Accessibility

Categories

Upload Details

Usage Rights

Statistics

Rest schema design Presentation Transcript