Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Rest schema design

3,449 views

Published on

Designing a REST API is difficult, and relies on your understanding of the developers and their use case. This presentation talks through Socialtext, Netflix and LinkedIn's APIs and decisions they made.

Published in: Technology, Business
  • Be the first to comment

Rest schema design

  1. 1. Kirsten Jones, Technical Leader, Cisco Systems @synedra http://www.princesspolymath.com
  2. 2.  Building a resource map  Usability concerns  Interface design choices  Examples: Socialtext, Netflix, LinkedInKirsten Jones http://www.princesspolymath.com @synedra
  3. 3.  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
  4. 4.  Resource map  Support reasonable cross-referenced resources  Expandability of resources  Explicit declaration of resource structure  Hyperlinking related resourcesKirsten Jones http://www.princesspolymath.com @synedra
  5. 5.  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
  6. 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 languageKirsten Jones http://www.princesspolymath.com @synedra
  7. 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, simplicityKirsten Jones http://www.princesspolymath.com @synedra
  8. 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 parametersKirsten Jones http://www.princesspolymath.com @synedra
  9. 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/pagesKirsten Jones http://www.princesspolymath.com @synedra
  10. 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 resourcesKirsten Jones http://www.princesspolymath.com @synedra
  11. 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. 12.  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
  13. 13.  /catalog/titles  Movies, TV shows  /catalog/people  Actors, directors  /users  Queue management, recommendationsKirsten Jones http://www.princesspolymath.com @synedra
  14. 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 informationKirsten Jones http://www.princesspolymath.com @synedra
  15. 15. <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
  16. 16. <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
  17. 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. 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,directorsKirsten Jones http://www.princesspolymath.com @synedra
  19. 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 treeKirsten Jones http://www.princesspolymath.com @synedra
  20. 20.  Social Network  Deeply Interlinked  Rich Information  Many potential use casesKirsten Jones http://www.princesspolymath.com @synedra
  21. 21.  Support many use cases  Provide control over response size  Limit overall call volume  Exercise consistencyKirsten Jones http://www.princesspolymath.com @synedra
  22. 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 resourcesKirsten Jones http://www.princesspolymath.com @synedra
  23. 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 queriesKirsten Jones http://www.princesspolymath.com @synedra
  24. 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 consistentKirsten Jones http://www.princesspolymath.com @synedra
  25. 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
  26. 26.  /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
  27. 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 experienceKirsten Jones http://www.princesspolymath.com @synedra
  28. 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. 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 downKirsten Jones http://www.princesspolymath.com @synedra
  30. 30.  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

×