1. Getting Serious with Versioned APIs in Scala Derrick Isaacson, Director of Development

2. Paid Free TIE

3. Evolvability

5. Web Site or Web Service Servers return XML IDs -> more HTTP requests Auth tokens, caching, content type negotiation Error status codes –> retries More XML, JPEG, other formats Series of rendering steps

6. There is no magic dust that makes an HTTP request a web service request. -Leonard Richardson & Sam Ruby, RESTful Web Services

7. What is a web service?

8. Distributed Computer Architectures Distributed memory RPC services RESTful services Distributed file systems P2P networks Streaming media

11. Extensibility of REST Fielding Dissertation Section 4.1.2

12. REST Components Data ElementModern Web ExamplesVersioning resourcethe intended conceptual target of a hypertext reference resource identifierURL, URN representationHTML document, JPEG image representation metadatamedia type, last-modified time control dataif-modified-since, cache- control

13. 1. Versioning the Resource (not the representation!) Representational State Transfer "The on-going mistake with distributed systems is focusing on the communication layer rather than a shared state layer. I argue that the shared state focus is necessary and sufficient to address all distributed system issues, whereas the communication layer is neither necessary nor sufficient." -David Cheriton, Distributed Systems Lecture Notes, ch. 3

14. 1. Evolving the Resource (not the representation!) 1.Uniform identification of resources 2.Uniform resource manipulation 3.Representation separate from the identity 4.Hypermedia as the engine of application state 5.Self-descriptive messages

15. 1. Phil the Spiders Floor Plan Photo by Matt Knoth http://www.flickr.com/photos/mattknoth/1473762553/sizes/o/in/photostream/

16. 1. Evolving the Resource http://lucidchart.com/docs/MyHome/v1http://lucidchart.com/docs/MyHome/v2

17. REST Components Data ElementModern Web ExamplesVersioning resourcethe intended conceptual target of a hypertext reference URLs resource identifierURL, URN representationHTML document, JPEG image representation metadatamedia type, last-modified time control dataif-modified-since, cache- control

18. 2. Evolving the Resource Identifier 1.Uniform identification of resources 2.Uniform resource manipulation 3.Representation separate from the identity 4.Hypermedia as the engine of application state 5.Self-descriptive messages

19. 2. Evolving URLs & Hypermedia … 123 http://lucidchart.com/imgs/123 http://images.lucidchart.com/imgs/123

20. 2. Evolving URLs & Hypermedia … http://images.lucidchart.com/imgs/123

21. 2. Evolving URLs & Uniform Response Codes http://lucidchart.com/imgs/123http://images.lucidchart.com/imgs/123 200 OK … Error Not Found 404 Not Found … … 301 Moved Permanently Location: http://images... … fail

22. 2. Hypermedia with Scala & Play #routes GET /users/{id} lucid.getUser(id) def getUser(id: Int) = { val accountURI = routes.App.userAccount(id) val template = User(accountURI) Ok(template) }

23. 2. Evolving URLs with Scala & Play # Images moved permanently GET /imgs/{id} lucid.redirectImages(id) def redirectImages(id: Int) = { val location = http://images.lucidchart.com/images/+id Redirect(location) }

24. REST Components Data ElementModern Web ExamplesVersioning resourcethe intended conceptual target of a hypertext reference URLs resource identifierURL, URN Hypermedia & Uniform Status Codes representationHTML document, JPEG image representation metadatamedia type, last-modified time control dataif-modified-since, cache-control

25. 3. Self-descriptive Messages GET /users/123 HTTP 1.1 Host:example.com User-Agent:XYZ 1.1 Accept:text/html, application/xhtml+xml, application/xml Keep-Alive:300 Connection:keep-alive If-Modified-Since:Fri, 02 Sep 2013 16:47:31 GMT If-None-Match:"600028c-59fb-474f6852c9dab" Cache-Control:max-age=60 Date:Fri, 02 Sep 2013 16:47:31 GMT Via: 1.0, myproxy, 1.1 lucidchart.com (Apache/1.1) Authorization: Bearer mF_9.B5f-4.1JqM

26. 3. Self-descriptive Messages HTTP/1.1 200 OK Date:Sun, 04 Oct 2013 19:36:25 GMT Server:Apache/2.2.11 (Debian) Last-Modified:Fri, 02 Oct 2013 16:48:39 GMT Etag:"600028c-59fb-474f6852c9dab" Cache-Control: max-age=300 Accept-Ranges: bytes Vary:Accept-Encoding Content-Type: application/xml Content-Encoding: gzip Content-Length: 7160 Keep-Alive:timeout=15,max=91 Connection:Keep-Alive

27. 3. Evolving Resource Metadata & Control Data 1.Uniform identification of resources 2.Uniform resource manipulation 3.Representation separate from the identity 4.Hypermedia as the engine of application state 5.Self-descriptive messages

28. REST Components Data ElementModern Web ExamplesVersioning resourcethe intended conceptual target of a hypertext reference URLs resource identifierURL, URNHypermedia & Uniform Status Codes representationHTML document, JPEG image representation metadatamedia type, last-modified time Self-descriptive w/ Uniform Headers control dataif-modified-since, cache- control

29. 4. Evolving Representations GET /images/123 … 200 OK HTTP 1.1 Content-Type: application/xml … success 123 MTIzNmEyMTM…= GET /images/123 Accept: image/jpeg … 200 OK HTTP 1.1 Content-Type: image/jpeg … (jpeg image)

30. 4. Evolving Representations Standard media types! http://microformats.org/ http://www.iana.org/assignments/media-types

31. GET /users/123 { name: John Smith, phone: 000-000-0000, email: john@example.com, photo: YWZzYSAyMzR2NQzJ2dzLmZhc20uLC8uLA==, groups: [ { id: 234, name: Team A, members: […] }, … ], account: { id: 345, company: Big Enterprise, …}, books: [ { id: 456, name: RESTful Web Services, publishDate: … }, { id: 567, name: REST in Practice, … }, … ], … { name: John Smith, phone: 000-000-0000, email: john@example.com, photo: https://lucidchart.com/images/abc, groups: https://lucidchart.com/groups?user=123 account: https://lucidchart.com/, books: https://books.example.com/catalog?ids=456…, … }

32. 4. Custom Media Types GET /diagrams/v1/123 HTTP/1.1 … GET /diagrams/v1/123 … X

33. 4. Custom Media Types GET /diagrams/123 HTTP/1.1 Accept: application/vnd.lucid.diagram+xml … GET /diagrams/123 HTTP/1.1 Accept: application/vnd.lucid.diagram -v2 +xml …

34. REST Components Data ElementModern Web ExamplesVersioning resourcethe intended conceptual target of a hypertext reference URLs resource identifierURL, URNHypermedia & Uniform Status Codes representationHTML document, JPEG image Content-type header, uniform media types, and general uniform interface representation metadatamedia type, last-modified timeSelf-descriptive w/ Uniform Headers control dataif-modified-since, cache-control

35. The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability.

36. Q & A http://www.lucidchart.com/jobs