Published on

I presented our Napster REST API at the LAJUG

1 Comment
  • Hi Stephen,

    Can you use the napster API for commercial use in an iphone app?

    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide


  1. 1. Napster REST API<br />
  2. 2. Napster<br />We are a Best Buy company <br />We are the best deal on the internet<br />$5 a month for 5 downloadable MP3s + Unlimited streaming of 10million tracks<br />We have a brand new site<br /><br />We have a live REST API since January<br /><br />We are actively working on putting the music on<br />Phones, Bluray Players, IPTVs & pretty much all the connected devices <br />We are also working with developers to create music apps<br />one app so far (<br />The API team is a small agile team of 6<br />We started the project in July and released the first version for the CES at January<br />
  3. 3. Agenda<br />What’s REST?<br />Quick tutorial on REST<br />Four guiding principles of REST<br />JAX-RS <br />Specification <br />Implementations<br />Napster REST API Demo<br />Napster REST API Architecture<br />Security<br />Response Format<br />Caching<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  4. 4. Agenda<br />What’s REST?<br />Quick tutorial on REST<br />Four guiding principles of REST<br />JAX-RS <br />Specification <br />Implementations<br />Napster REST API Demo<br />Napster REST API Architecture<br />Security<br />Response Format<br />Caching<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  5. 5. REST <br />Representational State Transfer <br /><br />User requests a Resource using URL<br /><br />/books <br /> /175 – Effective Java 2nd – Josh Bloch<br /> /952 – Windows MFC – Jeff Prosise<br /> /319 – C++ Programming – Bjarne Stroustrup<br /> /367 – UML Distilled – Martin Fowler<br /> /361 – Beginning Oracle – Tom Kyte<br /> /245 – Doman Driven Design – Eric Evans<br /> /298 – Lucene in Action – Erik Hatcher<br /> /395 – Ext GWT RIA – Grant Slender<br /> /392 – Tomcat 6 – Vivek Chopra<br /> /281 – RESTful Services – Sam Ruby<br />A Representation of the Resource is returned, and thus placing the client application in a State. <br />The Representation contains hyperlinks to other related Resources (individual books).<br />User clicks a hyperlink on the page<br />A Representation of another Resource is returned, and <br />thus causing a Transfer of client application State <br />This constant Transfer in client’s State through various Representations is <br />“Representational State Transfer”<br />
  6. 6. REST<br />Roy Fielding introduced REST Architectural Style for distributed hypermedia systems<br />
  7. 7. What is an ‘Architectural Style’?<br />An Architectural style is way of classifying architectures based on a set of “architectural constraints”<br />Gothic Architecture:<br />The ‘Clustered Columns’, ‘Pointed <br />Ribbed Vaults’ and the ‘Flying <br />Buttresses’ makes this a Gothic <br />Architecture<br />
  8. 8. REST Architectural Style Constraints<br /><ul><li>Client-Server – clients separated from server by uniform interface
  9. 9. Stateless – no client context stored on server
  10. 10. Cacheable – responses must define themselves as cacheable or not
  11. 11. Layered System – intermediary servers for load balancing, shared caches and enforce security
  12. 12. Code on Demand (optional) – customize client functionality by transferring logic (applets or javascript)
  13. 13. Uniform Interface – (next slide) </li></li></ul><li>Guiding principles of REST Interface<br /><ul><li>Identification of Resources
  14. 14. Individual resources are identified in requests using URIs
  15. 15. Manipulation of Resources
  16. 16. Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT, GET, POST, and DELETE
  17. 17. Self descriptive messages
  18. 18. Each message includes enough information on how to process the message. Responses also indicate their cacheability.
  19. 19. Hypermedia As The Engine Of the Application State (HATEOAS)
  20. 20. Related resources should be identified in the representation returned by providing their URIs</li></li></ul><li>What do we gain by going REST?<br />Conforming to the REST architectural style, will enable a distributed hypermedia system to have desirable emergent properties such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.<br />The largest known implementation of a system conforming to the REST architectural style is the WWW<br />
  21. 21. SOAP vs REST<br />SOAP Coffee Request<br />POST /askCoffeePolitelyHTTP/1.1<br />Host:<br />Content-Type: application/soap+xml; charset=utf-8<br />Content-Length: 100<br /><?xml version="1.0"?><br /><soap:Envelope<br />xmlns:soap=""<br />soap:encodingStyle=""><br /><soap:Bodyxmlns:m=""><br /><m:GetCoffee><br /> <m:NumberOfCoffees>1</m:NumberOfCoffees><br /> </m:GetCoffee><br /></soap:Body><br /></soap:Envelope><br />REST Coffee Request <br />GET /askCoffeePolitely/coffee?numberOfCoffees=1 HTTP/1.1<br />Host:<br />
  22. 22. SOAP vs REST<br />
  23. 23. Big advantage of REST<br />Your REST API<br />
  24. 24. Agenda<br />What’s REST?<br />Quick tutorial on REST<br />Four guiding principles of REST<br />JAX-RS <br />Specification <br />Implementations<br />Napster REST API Demo<br />Napster REST API Architecture<br />Security<br />Response Format<br />Caching<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  25. 25. JAX-RS Specification<br />Defines a set of Java APIs for development of Web Services build according to the REST architectural style. <br />Goals:<br />POJO Based - Provides a set of annotations and associated classes/interfaces that can be used with POJOs to expose them as Web Resources. <br />HTTP Centric - Provide clear mappings between HTTP & URI elements and corresponding API classes and annotations<br />Format Independent - Provide necessary pluggability of content types<br />Container Independent - Artifacts using the API will be deployable in a variety of web-tier containers <br />
  26. 26. JAX-RS Implementations<br />(as quoted by some one else)<br />there's a strange phenomenon regarding buses: you wait ages for one, then three come along at once! The same seems to be true for JAX-RS implementations. At the moment we have:<br />Restlet<br />probably the first REST framework, which existed prior to JAX-RS<br />CXF<br />which is a merger between XFire and Celtix (an Open Source ESB, sponsored by IONA and originally hosted at ObjectWeb) <br />Jersey<br />the JAX-RS Reference Implementation from Sun<br />RESTEasy<br />JBoss's JAX-RS project<br />
  27. 27. Agenda<br />What’s REST?<br />Introduction <br />SOAP vs REST<br />JAX-RS <br />Specification <br />Implementations<br />Napster REST API Demo<br />Napster REST API Architecture<br />Security<br />Response Format<br />Caching<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  28. 28. To get started on the API<br /><ul><li>Generate an API Key from developer portal
  29. 29. Signin using your napster account (or) Signup for a new account
  30. 30. Generate an API Key from [Keys & Account Info] section
  31. 31. Use this Excel sheet
  32. 32. Napster_API_Test_Console_Excel.xls
  33. 33. and copy/paste your API Key into the apiKey cell
  34. 34. Create a SessionKey
  35. 35. by clicking the CreateSession
  36. 36. and copy/paste your Session Key into sessionKey cell
  37. 37. Now you can access all the REST API Services (Resources) and get their XML/JSON representation</li></li></ul><li>REST API Services<br />Public API<br /><ul><li>Search
  38. 38. Genre
  39. 39. Album
  40. 40. Artist
  41. 41. Track
  42. 42. Radio
  43. 43. Automix
  44. 44. Napster Playlists
  45. 45. Staff Picks
  46. 46. Image
  47. 47. Security</li></ul>Private API<br /><ul><li>Security (login)
  48. 48. User
  49. 49. Track (playTrack)
  50. 50. Billboard</li></ul>Full API documentation is at the Portal <br />
  51. 51. Agenda<br />What’s REST?<br />Introduction <br />SOAP vs REST<br />JAX-RS <br />Specification <br />Implementations<br />Napster REST API Demo<br />Napster REST API Architecture<br />Security<br />Response Format<br />Caching<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  52. 52. Napster REST API Architecture<br />Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  53. 53. Quick note:<br />We put our Request details in ThreadLocal variables so that we don’t have to pass it around in method parameters<br /><ul><li>Since tomcat reuses threads we clear it before a request is done</li></li></ul><li>Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  54. 54. Security – API Key / Session Key<br /><ul><li>API Keys are
  55. 55. Generated by Developer Portal per Application
  56. 56. To be kept “SECRET”
  57. 57. To be used through Secure protocol (https://) only
  58. 58. Unchanging, it never Expires
  59. 59. Session Keys are
  60. 60. Generated by the Applications by calling “CreateSession” or “Login” APIs
  61. 61. Validated for all incoming API requests (except CreateSession, Login)
  62. 62. Can be used in an Unsecured protocol (http)
  63. 63. Good for only 6 hours, it Expires</li></li></ul><li>Security Model<br /><ul><li>Developers or Partners can have one of more API Keys, each one mapped to an application
  64. 64. For Selected Developers or Partners their API </li></ul> Key is given access to <br /><ul><li>One or more Private APIs
  65. 65. One or more Media Types (MP3, MP4, AAC, etc)</li></ul>API <br />Developer/Partner<br />API Keys<br />Private APIs<br />Media Types<br />
  66. 66. Interceptor to validate SessionKey<br />
  67. 67. Interceptor to Authorize Restricted Services<br />
  68. 68. Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  69. 69. REST Service Method<br />
  70. 70. Model class with JAXB Annotations<br />
  71. 71. Utility to build XML/JSON responses<br />
  72. 72. Response Output<br />We currently support XML, JSON & JSON-P formats<br />
  73. 73. JSON-P<br /><ul><li>Is used by for our JavaScript wrapper API
  74. 74.
  75. 75. To over come cross domain restriction with this hack:
  76. 76. varurl = ?format=json&callback=displayGenreDetails&sessionKey=BPGVjLGpzc
  77. 77. Yes, it’s wrong – but it seems to be the popular approach to get json contents from public APIs</li></li></ul><li>We also support “partial responses”<br />
  78. 78. Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  79. 79. Utility to build XML/JSON responses<br />
  80. 80. Utility refactored to set Cache Headers<br />New method<br />New method<br />
  81. 81. Response Cache Headers<br />Cache Headers<br />
  82. 82. Some observations…<br /><ul><li>Implementing HATEOAS can hurt when Caching
  83. 83. If the hyperlink in your responses contain session tracking information then you can’t cache this and reuse for other sessions
  84. 84. So, make sure the Cacheable responses don’t carry any session specific information
  85. 85. Sometimes, you don’t know the browser using your API
  86. 86. The API opens the door to many different device browser platforms like Konfabulator (the Yahoo Widget Library) or other embedded proprietary browsers
  87. 87. So, its probably a good idea to set “downstream-ttl” to value much shorter than the “max-age” when Caching on the Edge (just a thought)</li></li></ul><li>Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  88. 88. The Exception Class<br />Root Exception Class<br />Sub class<br />
  89. 89. The Error Class<br />
  90. 90. The Exception Mapper<br />
  91. 91. Error Handling / Error Format<br />XML<br />JSON<br />
  92. 92. Error Handling<br /><ul><li>We don’t have Application Error Codes, we map application errors to the closest HTTP Error Code.
  93. 93. We use actual HTTP Error Codes with an appropriate error message in the response</li></li></ul><li>Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  94. 94. First, we came up with some questions…<br /><ul><li>Do we even need versioning?
  95. 95. When do we make a minor version?
  96. 96. When do we make a major version?
  97. 97. How long are we going to be backward compatible?
  98. 98. How do we guarantee that this new fix is not a breaking change?
  99. 99. Are there any external factors that could affect our older versions?</li></li></ul><li>Then, some answers…<br /><ul><li>Do we even need versioning?
  100. 100. Sadly, yes
  101. 101. When do we make a minor/major version?
  102. 102. We are going to try hard to NOT make new versions by
  103. 103. defining the response tag elements right the first time
  104. 104. adding newer elements to the tail end of tag
  105. 105. We make a new version only when we have a breaking change
  106. 106. How long are we going to be backward compatible?
  107. 107. Let’s shoot forever, if we are lucky enough we’ll drop older versions
  108. 108. How do we guarantee that this small fix doesn’t break anything?
  109. 109. 70 APIs, 2 Versions, 2 Formats, 5 Different Country Codes
  110. 110. that’s 70 x 2 x 2 x 5 = 1400 tests (a little exaggeration there)
  111. 111. Are these any external factors that could affect our older versions?
  112. 112. You betcha… </li></li></ul><li>So, it came down to…<br /><ul><li>Having a simple versioning design
  113. 113. Keeping all the code base in one place without any branching so that its easier to code, maintain, refactor, debug
  114. 114. Having a “solid” CI Test Suite to test every little change</li></li></ul><li>Versioning Implementation<br />GenreRestServiceV10 Implementation<br />@Override<br /><ul><li>getGenres(){</li></ul>}<br />@Override<br /><ul><li>getTopAlbumsByGenreId(int genreId){</li></ul>}<br />GenreRestService Endpoint<br />/(1.0|1.1)/genres<br /><ul><li>getGenres()</li></ul>/(1.0)/genres/{genreId}/albums<br /><ul><li>getTopAlbumsByGenreId(int genreId)</li></ul>/(1.1)/genres/{genreId}<br /><ul><li>getGenreById(int genreId)</li></ul>3<br />1<br />GenreRestServiceV11 Implementation<br />@Override <br /><ul><li>getGenreById(int genreId){</li></ul>}<br />3<br />2<br />Service Version Map<br />Key<br />Value<br />
  115. 115. The Endpoint class<br />
  116. 116. Napster REST API Architecture<br />Security<br />Caching<br />Response Format<br />Error Handling<br />Versioning<br />Continuous Integration<br />
  117. 117. Continuous Integration<br />API QA <br />Remote<br />API_DEV<br />API_QA<br />API_AUTO_STAG<br />API_AUTO_PROD<br />
  118. 118. SoapUI to write the test suites<br />
  119. 119. Each version has its own set of tests<br />
  120. 120. ANT Contrib to run the SoapUI projects<br />
  121. 121. Targets to run dev, qa, stag & prod tests<br />
  122. 122. Hudson to build, deploy and test…<br />
  123. 123. SoapUI produces ton of log files<br />
  124. 124. A “tiny” little bash script…<br /><ul><li>To recursive find grep SoapUI log files directories
  125. 125. Make a list of failed test cases (*FAILED.txt files)
  126. 126. Prepend the server URL to make clickable hyper links
  127. 127. Email the Team</li></ul>Subject : API_DEV - SOAPUI FAILED TESTCASES<br />Email :<br />1 Test Cases Failed in 1.0 Services<br />===========================================<br /> <br /><br /> <br /> <br />2 Test Cases Failed in 1.1 Services<br />===========================================<br /> <br /><br /><br />
  128. 128. Continuous Integration<br />API QA <br />Remote<br />API_DEV<br />API_QA<br />API_AUTO_STAG<br />API_AUTO_PROD<br />
  129. 129. Another attempt @ mocking SOAP<br />...a little difficult to understand <br />
  130. 130. REST<br />…RESTeasy <br />
  131. 131. Questions?<br />