LAJUG Napster REST API

  • 1,920 views
Uploaded on

I presented our Napster REST API at the LAJUG

I presented our Napster REST API at the LAJUG

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
  • Hi Stephen,

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

    thanks
    Are you sure you want to
    Your message goes here
    Be the first to like this
No Downloads

Views

Total Views
1,920
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
0
Comments
1
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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
  • 8. REST Architectural Style Constraints
    • Client-Server – clients separated from server by uniform interface
    • 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)
    • 13. Uniform Interface – (next slide)
  • Guiding principles of REST Interface
    • Identification of Resources
    • 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)
    • 20. Related resources should be identified in the representation returned by providing their URIs
  • What do we gain by going REST?
    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.
    The largest known implementation of a system conforming to the REST architectural style is the WWW
  • 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
  • 28. To get started on the API
    • Generate an API Key from developer portal http://developer.napster.com
    • 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
    • 37. Now you can access all the REST API Services (Resources) and get their XML/JSON representation
  • REST API Services
    Public API
    Private API
    Full 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
  • 53. Quick note:
    We put our Request details in ThreadLocal variables so that we don’t have to pass it around in method parameters
    • Since tomcat reuses threads we clear it before a request is done
  • Security
    Caching
    Response Format
    Error Handling
    Versioning
    Continuous Integration
  • 54. Security – API Key / Session Key
    • API Keys are
    • 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)
    • 63. Good for only 6 hours, it Expires
  • Security Model
    • Developers or Partners can have one of more API Keys, each one mapped to an application
    • 64. For Selected Developers or Partners their API
    Key is given access to
    • One or more Private APIs
    • 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
  • 73. JSON-P
    • Is used by for our JavaScript wrapper API
    • 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
    • 77. Yes, it’s wrong – but it seems to be the popular approach to get json contents from public APIs
  • We also support “partial responses”
  • 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
  • 82. Some observations…
    • Implementing HATEOAS can hurt when Caching
    • 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
    • 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)
  • Security
    Caching
    Response Format
    Error Handling
    Versioning
    Continuous Integration
  • 88. The Exception Class
    Root Exception Class
    Sub class
  • 89. The Error Class
  • 90. The Exception Mapper
  • 91. Error Handling / Error Format
    XML
    JSON
  • 92. Error Handling
    • We don’t have Application Error Codes, we map application errors to the closest HTTP Error Code.
    • 93. We use actual HTTP Error Codes with an appropriate error message in the response
  • Security
    Caching
    Response Format
    Error Handling
    Versioning
    Continuous Integration
  • 94. First, we came up with some questions…
    • Do we even need versioning?
    • 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?
    • 99. Are there any external factors that could affect our older versions?
  • Then, some answers…
    • Do we even need versioning?
    • 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?
    • 112. You betcha… 
  • So, it came down to…
    • Having a simple versioning design
    • 113. Keeping all the code base in one place without any branching so that its easier to code, maintain, refactor, debug
    • 114. Having a “solid” CI Test Suite to test every little change
  • Versioning Implementation
    GenreRestServiceV10 Implementation
    @Override
    • getGenres(){
    }
    @Override
    • getTopAlbumsByGenreId(int genreId){
    }
    GenreRestService Endpoint
    /(1.0|1.1)/genres
    • getGenres()
    /(1.0)/genres/{genreId}/albums
    • getTopAlbumsByGenreId(int genreId)
    /(1.1)/genres/{genreId}
    • getGenreById(int genreId)
    3
    1
    GenreRestServiceV11 Implementation
    @Override
    • getGenreById(int genreId){
    }
    3
    2
    Service Version Map
    Key
    Value
  • 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
  • 124. A “tiny” little bash script…
    • To recursive find grep SoapUI log files directories
    • 125. Make a list of failed test cases (*FAILED.txt files)
    • 126. Prepend the server URL to make clickable hyper links
    • 127. Email the Team
    Subject : 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?