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

DWX2018: Wie designt man eigentlich ein schönes...

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!

Manuel Meyer

June 25, 2018
Tweet

More Decks by Manuel Meyer

Other Decks in Programming

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

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

    /customer/{id} PUT /customer/{id}. «Operations» «Resources»
  9. The Challenges of REST ▪ It’s just too easy. ▪

    Too many options ▪ The «Glory» of REST -> Too many options ▪ N + 1 Problem & Mobile Apps
  10. It’s just too easy… Roy Fielding, 2000 „Unfortunately, people are

    fairly good at short-term design, and usually awful at long-term design“
  11. Too many options… ▪ REST is an Architectural Style ▪

    It is NOT a Standard. + Rapid Application Development Tooling.
  12. 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
  13. 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
  14. 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).
  15. 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
  16. Principle 3: Define Use Cases «Find use cases that help

    increasing the metrics of Principle 2» https://www.manning.com/books/irresistible-apis
  17. 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
  18. 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.
  19. 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.
  20. 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
  21. 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/
  22. 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
  23. 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
  24. 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
  25. 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/