DWX2018: Wie designt man eigentlich ein schönes REST API?

Wir leben heutzutage in der Welt der Daten und APIs. Jeder bietet seine Daten über APIs an und REST (Representational State Transfer) hat sich als Standardparadigma durchgesetzt. Aber was ist REST eigentlich genau und was nicht? Und warum hat sich gerade REST durchgesetzt? Nach einem kurzen Einblick in die Geschichte von REST tauchen wir ein in den REST API Design Lifecycle und die Best Practices zum API Design. Wir schauen dabei auch auf die REST-Implementierungen der grossen Players im Markt und stellen sicher, dass ihr nächstes REST API ihre Konsumenten begeistern wird!

Transcript

1. BASLE BERN BRUGG DÜSSELDORF FRANKFURT A.M. FREIBURG I.BR. GENEVA
   HAMBURG COPENHAGEN LAUSANNE MUNICH STUTTGART VIENNA ZURICH
   Wie designt man eigentlich ein
   schönes REST API?
   Manuel Meyer, Trivadis AG
   http://manuelmeyer.net
   @manumeyer1
   25.06.2018
   

   View Slide

2. Über mich…
   Consultant & Trainer for .NET
   C#/XAML, Integration, Azure,
   Troubleshooting & Performance
   Management
   MVP for Visual Studio & Dev. Tools
   www.azurezurichusergroup.com
   www.dotnetday.ch
   Manuel Meyer
   www.manuelmeyer.net
   @manumeyer1
   

   View Slide

3. Die «API Economy»
   „The API economy is an enabler for
   turning a business or organization into
   a platform“
   Gartner, 2016
   https://www.gartner.com/smarterwithgartner/welcome-to-the-api-economy/
   

   View Slide

4. Die «API Economy»
   „Make APIs the basis of
   your digital strategy“
   Gartner, 2017
   https://www.gartner.com/smarterwithgartner/the-road-to-the-api-economy/
   

   View Slide

5. Agenda
   1. The History of REST
   2. The Challenges of REST
   3. REST API Design
   4. The Future of REST.
   

   View Slide

6. The History of REST
   

   View Slide

7. Die Geschichte von REST
   1960
   Photo credit: Pargon on Visual Hunt
   

   View Slide

8. View Slide

9. 1970
   RPC
   

   View Slide

10. RPC
    

    View Slide

11. Die Geschichte von REST
    

    View Slide

12. View Slide

13. RPC
    1980
    Hypertext
    

    View Slide

14. 1990
    XML-RPC
    

    View Slide

15. 1998
    SOAP
    

    View Slide

16. 1998
    SOAP
    

    View Slide

17. Die Geschichte von REST
    „REST started as a
    model how the web and
    web apps should work.“
    Roy Fielding, 2000
    https://www.youtube.com/watch?v=w5j2KwzzB-0
    http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
    

    View Slide

18. Die Geschichte von REST
    Roy Fielding, 2000
    https://www.youtube.com/watch?v=w5j2KwzzB-0
    http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
    – Simple
    – Scalable
    – Reliable
    – Extensible.
    

    View Slide

19. SOAP vs. REST
    SOAP, XML
    GetCustomer()
    UpdateCustomer()
    REST, HTTP
    GET /customer/{id}
    PUT /customer/{id}.
    «Operations» «Resources»
    

    View Slide

20. Richardson Maturity Model
    https://www.martinfowler.com/articles/richardsonMaturityModel.html
    /Game
    GET /Game
    HATEOAS
    

    View Slide

21. HATEOAS
    Hypermedia as the engine of application state
    

    View Slide

22. The Challenges of REST
    

    View Slide

23. The Challenges of REST
    ▪ It’s just too easy.
    ▪ Too many options
    ▪ The «Glory» of REST -> Too many options
    ▪ N + 1 Problem & Mobile Apps
    

    View Slide

24. It’s just too easy…
    Roy Fielding, 2000
    „Unfortunately, people are
    fairly good at short-term
    design, and usually awful at
    long-term design“
    

    View Slide

25. Too many options…
    ▪ REST is an Architectural Style
    ▪ It is NOT a Standard.
    +
    Rapid Application Development Tooling.
    

    View Slide

26. Demo VS RAD
    

    View Slide

27. The glory of REST…
    «Hypermedia ist
    eine Erweiterung
    von Hypertext»
    «Der Rest von REST»
    «Der heilige Gral»
    «Müll».
    HATEOAS =
    Hypermedia as the Engine of Application State
    

    View Slide

28. The glory of REST…
    ▪ NO HATEOAS Standard!
    HAL
    JSON-LD
    SIREN
    Collection+JSON
    JSON:API
    

    View Slide

29. Provide Documentation
    Wild Wild REST
    

    View Slide

30. The N + 1 Problem and Mobile Apps
    https://marmelab.com/blog/2017/09/04/dive-into-graphql-part-i-what-s-wrong-with-rest.html
    

    View Slide

31. REST API Design
    

    View Slide

32. API Design Process
    1. Determine the Business Value
    2. Choose Metrics
    3. Define Use Cases
    4. Design the API
    Design
    Develop
    Iterate
    https://www.manning.com/books/irresistible-apis
    Develop
    Design
    

    View Slide

33. Principle 1: Determine Business Value
    • API for Everybody (no use cases)
    • Devs rebuilt Netflix
    • New Terms of Service
    • Frustration!
    • Success with Device Vendors
    • Re-Focus of APIs & Close Public APIs
    -> Unpopular with devs but high business value
    -> Specify Business Value (e.g. Monetization, Usage,
    Partner Retention, Market Dominance).
    

    View Slide

34. Principle 2: Choose Metrics
    ▪ Monetization
    ▪ Trial account conversions
    ▪ High Volume Accounts
    ▪ Usage
    ▪ Frequency of Interaction
    ▪ Partner Retention
    ▪ Applications active after 3, 6, 9 months
    ▪ Market Dominance
    ▪ Number of devices
    https://www.manning.com/books/irresistible-apis
    

    View Slide

35. Principle 3: Define Use Cases
    «Find use cases that help increasing
    the metrics of Principle 2»
    https://www.manning.com/books/irresistible-apis
    

    View Slide

36. Principle 3: Define & Document Use Cases
    https://www.manning.com/books/irresistible-apis
    

    View Slide

37. Principle 4: Design the API & Iterate
    1. Follow REST = HTTP Verbs, Resources, Status Codes
    2. Provide Documentation
    3. Use Versioning
    4. Allow paging, filtering, sorting
    5. Provide a way to limit fields
    -> API First Design!
    https://www.manning.com/books/irresistible-apis
    Develop
    Design
    

    View Slide

38. 1. Follow REST = HTTP Verbs, Resources, Status Codes
    GET /photos/1234
    GET /photos/1234/delete_photo
    DELETE /photos/1234
    -> Developers have an expectation of REST.
    

    View Slide

39. 2. Documentation
    +
    

    View Slide

40. 2. Documentation
    https://petstore.swagger.io/v2/swagger.json
    

    View Slide

41. 2. Documentation
    http://editor.swagger.io/
    

    View Slide

42. Demo Swagger Editor
    

    View Slide

43. Code Generation
    http://NSwag.org
    

    View Slide

44. Versioning
    ▪ Major Releases
    ▪ Use url: www.test.ch/api/v1.0/...
    ▪ Minor Releases
    ▪ Use Header: Accept: application/myapp-v3+xml
    Important: Start with versioning in mind.
    

    View Slide

45. Paging, Sorting, Filtering, Restricting Fields
    ▪ Paging
    ▪ api/v1.0/game?page=2&pageSize=20
    ▪ Sorting
    ▪ api/v1.0/game?orderBy=id
    ▪ api/v1.0/game?orderByDesc=id
    ▪ Filtering
    ▪ api/v1.0/game?year=2018
    ▪ Restricting Fields
    ▪ api/v1.0/game?fields=id,name,date
    

    View Slide

46. The future of REST
    

    View Slide

47. The future of REST?
    ▪ REST is CRUD
    ▪ CRUD is Bad!
    ▪ Where is the domain language?
    ▪ DDD and Event Sourcing to the rescue!
    https://www.thenativeweb.io/blog/2017-10-25-09-46-ddd-and-co-part-1-whats-wrong-with-crud/
    

    View Slide

48. Recap
    

    View Slide

49. The Challenges of REST
    ▪ It’s just too easy.
    ▪ Too many options. No standard.
    ▪ The «Glory» of REST -> Too many options
    ▪ N + 1 Problem & Mobile Apps
    

    View Slide

50. API Design Process
    1. Determine the Business Value
    2. Choose Metrics
    3. Define Use Cases
    4. Design the API
    Design
    Develop
    Iterate
    https://www.manning.com/books/irresistible-apis
    Develop
    Design
    

    View Slide

51. Principle 4: Design the API & Iterate
    1. Follow REST = HTTP Verbs, Resources, Status Codes
    2. Provide Documentation
    3. Use Versioning
    4. Allow paging, filtering, sorting.
    5. Provide a way to limit fields
    -> API First Design!
    https://www.manning.com/books/irresistible-apis
    Develop
    Design
    

    View Slide

52. Case Study: Applied REST API Design
    “How I Used RAML to
    Embed a RESTful API into
    DOOM” –Jeff Harris
    https://blogs.mulesoft.com/dev/api-dev/how-embed-restful-api-doom-game/
    https://www.youtube.com/watch?v=Km6_AwzZmf0
    https://github.com/jeff-1amstudios/restful-doom/
    

    View Slide

53. Thank You!
    Manuel Meyer (manuel.meyer@trivadis.com)
    www.manuelmeyer.net
    @manumeyer1
    

    View Slide