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
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
9. 1970 RPC
10. RPC
11. Die Geschichte von REST
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