The document describes Napster's REST API. Napster provides a REST API for developers to access its music catalog and build applications. The API allows searching, retrieving metadata and streaming music. The API team is small with 6 members and started the project in July, releasing the first version in January for the CES event. The API documentation is available at http://developer.napster.com/docs/.

1. Napster REST API

2. Napster We are a Best Buy company We are the best deal on the internet $5 a month for 5 downloadable MP3s + Unlimited streaming of 10million tracks We have a brand new site http://music.napster.com We have a live REST API since January http://developer.napster.com We are actively working on putting the music on Phones, Bluray Players, IPTVs & pretty much all the connected devices We are also working with developers to create music apps one app so far (http://twt.fm) The API team is a small agile team of 6 We started the project in July and released the first version for the CES at January

3. Agenda What’s REST? Quick tutorial on REST Four guiding principles of REST JAX-RS Specification Implementations Napster REST API Demo Napster REST API Architecture Security Response Format Caching Error Handling Versioning Continuous Integration

4. Agenda What’s REST? Quick tutorial on REST Four guiding principles of REST JAX-RS Specification Implementations Napster REST API Demo Napster REST API Architecture Security Response Format Caching Error Handling Versioning Continuous Integration

5. REST Representational State Transfer www.library.com User requests a Resource using URL http://www.library.com/books /books /175 – Effective Java 2nd – Josh Bloch /952 – Windows MFC – Jeff Prosise /319 – C++ Programming – Bjarne Stroustrup /367 – UML Distilled – Martin Fowler /361 – Beginning Oracle – Tom Kyte /245 – Doman Driven Design – Eric Evans /298 – Lucene in Action – Erik Hatcher /395 – Ext GWT RIA – Grant Slender /392 – Tomcat 6 – Vivek Chopra /281 – RESTful Services – Sam Ruby A Representation of the Resource is returned, and thus placing the client application in a State. The Representation contains hyperlinks to other related Resources (individual books). User clicks a hyperlink on the page A Representation of another Resource is returned, and thus causing a Transfer of client application State This constant Transfer in client’s State through various Representations is “Representational State Transfer”

6. REST Roy Fielding introduced REST Architectural Style for distributed hypermedia systems

7. What is an ‘Architectural Style’? An Architectural style is way of classifying architectures based on a set of “architectural constraints” Gothic Architecture: The ‘Clustered Columns’, ‘Pointed Ribbed Vaults’ and the ‘Flying Buttresses’ makes this a Gothic Architecture

9. Stateless – no client context stored on server

10. Cacheable – responses must define themselves as cacheable or not

11. Layered System – intermediary servers for load balancing, shared caches and enforce security

12. Code on Demand (optional) – customize client functionality by transferring logic (applets or javascript)

14. Individual resources are identified in requests using URIs

15. Manipulation of Resources

16. Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT, GET, POST, and DELETE

17. Self descriptive messages

18. Each message includes enough information on how to process the message. Responses also indicate their cacheability.

19. Hypermedia As The Engine Of the Application State (HATEOAS)

21. SOAP vs REST SOAP Coffee Request POST /askCoffeePolitelyHTTP/1.1 Host: www.coffee.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: 100 <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Bodyxmlns:m="http://www.coffee.com/askCoffeePolitely"> <m:GetCoffee> <m:NumberOfCoffees>1</m:NumberOfCoffees> </m:GetCoffee> </soap:Body> </soap:Envelope> REST Coffee Request GET /askCoffeePolitely/coffee?numberOfCoffees=1 HTTP/1.1 Host: www.coffee.com

22. SOAP vs REST

23. Big advantage of REST Your REST API

24. Agenda What’s REST? Quick tutorial on REST Four guiding principles of REST JAX-RS Specification Implementations Napster REST API Demo Napster REST API Architecture Security Response Format Caching Error Handling Versioning Continuous Integration

25. JAX-RS Specification Defines a set of Java APIs for development of Web Services build according to the REST architectural style. Goals: POJO Based - Provides a set of annotations and associated classes/interfaces that can be used with POJOs to expose them as Web Resources. HTTP Centric - Provide clear mappings between HTTP & URI elements and corresponding API classes and annotations Format Independent - Provide necessary pluggability of content types Container Independent - Artifacts using the API will be deployable in a variety of web-tier containers

26. JAX-RS Implementations (as quoted by some one else) 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: Restlet probably the first REST framework, which existed prior to JAX-RS CXF which is a merger between XFire and Celtix (an Open Source ESB, sponsored by IONA and originally hosted at ObjectWeb) Jersey the JAX-RS Reference Implementation from Sun RESTEasy JBoss's JAX-RS project

27. Agenda What’s REST? Introduction SOAP vs REST JAX-RS Specification Implementations Napster REST API Demo Napster REST API Architecture Security Response Format Caching Error Handling Versioning Continuous Integration

29. Signin using your napster account (or) Signup for a new account

30. Generate an API Key from [Keys & Account Info] section

31. Use this Excel sheet

32. Napster_API_Test_Console_Excel.xls

33. and copy/paste your API Key into the apiKey cell

34. Create a SessionKey

35. by clicking the CreateSession

36. and copy/paste your Session Key into sessionKey cell

38. Genre

39. Album

40. Artist

41. Track

42. Radio

43. Automix

44. Napster Playlists

45. Staff Picks

46. Image

48. User

49. Track (playTrack)

50. BillboardFull API documentation is at the Portal  http://developer.napster.com/docs/

51. Agenda What’s REST? Introduction SOAP vs REST JAX-RS Specification Implementations Napster REST API Demo Napster REST API Architecture Security Response Format Caching Error Handling Versioning Continuous Integration

52. Napster REST API Architecture Security Caching Response Format Error Handling Versioning Continuous Integration

55. Generated by Developer Portal per Application

56. To be kept “SECRET”

57. To be used through Secure protocol (https://) only

58. Unchanging, it never Expires

59. Session Keys are

60. Generated by the Applications by calling “CreateSession” or “Login” APIs

61. Validated for all incoming API requests (except CreateSession, Login)

62. Can be used in an Unsecured protocol (http)

65. One or more Media Types (MP3, MP4, AAC, etc)API Developer/Partner API Keys Private APIs Media Types

66. Interceptor to validate SessionKey

67. Interceptor to Authorize Restricted Services

68. Security Caching Response Format Error Handling Versioning Continuous Integration

69. REST Service Method

70. Model class with JAXB Annotations

71. Utility to build XML/JSON responses

72. Response Output We currently support XML, JSON & JSON-P formats

74. http://developer.napster.com/js/api.js

75. To over come cross domain restriction with this hack:

76. varurl = http://api.napster.com:8080/rest/1.1/genres/1 ?format=json&callback=displayGenreDetails&sessionKey=BPGVjLGpzc

78. Security Caching Response Format Error Handling Versioning Continuous Integration

79. Utility to build XML/JSON responses

80. Utility refactored to set Cache Headers New method New method

81. Response Cache Headers Cache Headers

83. If the hyperlink in your responses contain session tracking information then you can’t cache this and reuse for other sessions

84. So, make sure the Cacheable responses don’t carry any session specific information

85. Sometimes, you don’t know the browser using your API

86. The API opens the door to many different device browser platforms like Konfabulator (the Yahoo Widget Library) or other embedded proprietary browsers

88. The Exception Class Root Exception Class Sub class

89. The Error Class

90. The Exception Mapper

91. Error Handling / Error Format XML JSON

95. When do we make a minor version?

96. When do we make a major version?

97. How long are we going to be backward compatible?

98. How do we guarantee that this new fix is not a breaking change?

100. Sadly, yes

101. When do we make a minor/major version?

102. We are going to try hard to NOT make new versions by

103. defining the response tag elements right the first time

104. adding newer elements to the tail end of tag

105. We make a new version only when we have a breaking change

106. How long are we going to be backward compatible?

107. Let’s shoot forever, if we are lucky enough we’ll drop older versions

108. How do we guarantee that this small fix doesn’t break anything?

109. 70 APIs, 2 Versions, 2 Formats, 5 Different Country Codes

110. that’s 70 x 2 x 2 x 5 = 1400 tests (a little exaggeration there)

111. Are these any external factors that could affect our older versions?

113. Keeping all the code base in one place without any branching so that its easier to code, maintain, refactor, debug

115. The Endpoint class

116. Napster REST API Architecture Security Caching Response Format Error Handling Versioning Continuous Integration

117. Continuous Integration API QA Remote API_DEV API_QA API_AUTO_STAG API_AUTO_PROD

118. SoapUI to write the test suites

119. Each version has its own set of tests

120. ANT Contrib to run the SoapUI projects

121. Targets to run dev, qa, stag & prod tests

122. Hudson to build, deploy and test…

123. SoapUI produces ton of log files

125. Make a list of failed test cases (*FAILED.txt files)

126. Prepend the server URL to make clickable hyper links

127. Email the TeamSubject : API_DEV - SOAPUI FAILED TESTCASES Email : 1 Test Cases Failed in 1.0 Services =========================================== http://ci01.napster.com:8080/hudson/job/API_DEV/ws/NapsterApi/test-output/soapui/1.0/dev01/UserRestServiceTestSuite-getNewArrivals-getNewArrivals-0-FAILED.txt 2 Test Cases Failed in 1.1 Services =========================================== http://ci01.napster.com:8080/hudson/job/API_DEV/ws/NapsterApi/test-output/soapui/1.1/dev01/PurchaseTestSuite-TestPurchaseWithCredits-PurchaseTrackUsingCredits-0-FAILED.txt http://ci01.napster.com:8080/hudson/job/API_DEV/ws/NapsterApi/test-output/soapui/1.1/dev01/RadioRestServiceTestSuite-getRadioStationTracksByStationId-getRadioStationTracksByStationId-0-FAILED.txt

128. Continuous Integration API QA Remote API_DEV API_QA API_AUTO_STAG API_AUTO_PROD

129. Another attempt @ mocking SOAP ...a little difficult to understand

130. REST …RESTeasy 

131. Questions?