Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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!

7252086bae9203045dd7f5664fd96a07?s=128

Manuel Meyer

June 25, 2018
Tweet

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
  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
  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/
  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/
  5. Agenda 1. The History of REST 2. The Challenges of

    REST 3. REST API Design 4. The Future of REST.
  6. The History of REST

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

    Hunt
  8. None
  9. 1970 RPC

  10. RPC

  11. Die Geschichte von REST

  12. 1971

  13. RPC 1980 Hypertext

  14. 1990 XML-RPC

  15. 1998 SOAP

  16. 1998 SOAP

  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
  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.
  19. SOAP vs. REST SOAP, XML GetCustomer() UpdateCustomer() REST, HTTP GET

    /customer/{id} PUT /customer/{id}. «Operations» «Resources»
  20. Richardson Maturity Model https://www.martinfowler.com/articles/richardsonMaturityModel.html /Game GET /Game HATEOAS

  21. HATEOAS Hypermedia as the engine of application state

  22. The Challenges of REST

  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
  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“
  25. Too many options… ▪ REST is an Architectural Style ▪

    It is NOT a Standard. + Rapid Application Development Tooling.
  26. Demo VS RAD

  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
  28. The glory of REST… ▪ NO HATEOAS Standard! HAL JSON-LD

    SIREN Collection+JSON JSON:API
  29. Provide Documentation Wild Wild REST

  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

  31. REST API Design

  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
  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).
  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
  35. Principle 3: Define Use Cases «Find use cases that help

    increasing the metrics of Principle 2» https://www.manning.com/books/irresistible-apis
  36. Principle 3: Define & Document Use Cases https://www.manning.com/books/irresistible-apis

  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
  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.
  39. 2. Documentation +

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

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

  42. Demo Swagger Editor

  43. Code Generation http://NSwag.org

  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.
  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
  46. The future of REST

  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/
  48. Recap

  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
  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
  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
  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/
  53. Thank You! Manuel Meyer (manuel.meyer@trivadis.com) www.manuelmeyer.net @manumeyer1