Getting Serious with Versioned APIs in Scala

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

2. TIE Paid Free

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

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

14. 1. Evolving the Resource http://lucidchart.com/docs/MyHome/v1 http://lucidchart.com/docs/MyHome/v2

15. REST Components

16. 2. Evolving the Resource Identifier • Uniform identification of resources • Uniform resource manipulation • Representation separate from the identity • Hypermedia as the engine of application state • Self-descriptive messages

17. 2. Evolving URLs & Hypermedia <diagram> … <images> <image> <id>123</id> </image> </images> </diagram> http://lucidchart.com/imgs/123 http://images.lucidchart.com/imgs/123

18. 2. Evolving URLs & Hypermedia <diagram> … <images> <image> <id> http://images.lucidchart.com/imgs/123 </id> </image> </images> </diagram>

19. 2. Evolving URLs & Uniform Response Codes 200 OK … <response> <status>Error</status> <msg>Not Found</msg> </response> http://lucidchart.com/imgs/123 http://images.lucidchart.com/imgs/123 404 Not Found … <userMsg> … </userMsg> 301 Moved Permanently Location: http://images... … fail

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

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

22. REST Components

23. 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

24. 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

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

26. REST Components

27. 4. Evolving Representations GET /images/123 … 200 OK HTTP 1.1 Content-Type: application/xml … <response> <status>success</status> <id>123</id> <image>MTIzNmEyMTM…=</image> </response> GET /images/123 Accept: image/jpeg … 200 OK HTTP 1.1 Content-Type: image/jpeg … (jpeg image)

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

29. { 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…”, … } 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”, … }, … ], …

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

31. 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 …

32. REST Components

33. “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.”

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