Slide 1
Slide 1 text
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
Slide 2
Slide 2 text
Ü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
Slide 3
Slide 3 text
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/
Slide 4
Slide 4 text
Die «API Economy»
„Make APIs the basis of
your digital strategy“
Gartner, 2017
https://www.gartner.com/smarterwithgartner/the-road-to-the-api-economy/
Slide 5
Slide 5 text
Agenda
1. The History of REST
2. The Challenges of REST
3. REST API Design
4. The Future of REST.
Slide 6
Slide 6 text
The History of REST
Slide 7
Slide 7 text
Die Geschichte von REST
1960
Photo credit: Pargon on Visual Hunt
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
1970
RPC
Slide 10
Slide 10 text
RPC
Slide 11
Slide 11 text
Die Geschichte von REST
Slide 12
Slide 12 text
1971
Slide 13
Slide 13 text
RPC
1980
Hypertext
Slide 14
Slide 14 text
1990
XML-RPC
Slide 15
Slide 15 text
1998
SOAP
Slide 16
Slide 16 text
1998
SOAP
Slide 17
Slide 17 text
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
Slide 18
Slide 18 text
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.
Slide 19
Slide 19 text
SOAP vs. REST
SOAP, XML
GetCustomer()
UpdateCustomer()
REST, HTTP
GET /customer/{id}
PUT /customer/{id}.
«Operations» «Resources»
Slide 20
Slide 20 text
Richardson Maturity Model
https://www.martinfowler.com/articles/richardsonMaturityModel.html
/Game
GET /Game
HATEOAS
Slide 21
Slide 21 text
HATEOAS
Hypermedia as the engine of application state
Slide 22
Slide 22 text
The Challenges of REST
Slide 23
Slide 23 text
The Challenges of REST
▪ It’s just too easy.
▪ Too many options
▪ The «Glory» of REST -> Too many options
▪ N + 1 Problem & Mobile Apps
Slide 24
Slide 24 text
It’s just too easy…
Roy Fielding, 2000
„Unfortunately, people are
fairly good at short-term
design, and usually awful at
long-term design“
Slide 25
Slide 25 text
Too many options…
▪ REST is an Architectural Style
▪ It is NOT a Standard.
+
Rapid Application Development Tooling.
Slide 26
Slide 26 text
Demo VS RAD
Slide 27
Slide 27 text
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
Slide 28
Slide 28 text
The glory of REST…
▪ NO HATEOAS Standard!
HAL
JSON-LD
SIREN
Collection+JSON
JSON:API
Slide 29
Slide 29 text
Provide Documentation
Wild Wild REST
Slide 30
Slide 30 text
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
Slide 31
Slide 31 text
REST API Design
Slide 32
Slide 32 text
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
Slide 33
Slide 33 text
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).
Slide 34
Slide 34 text
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
Slide 35
Slide 35 text
Principle 3: Define Use Cases
«Find use cases that help increasing
the metrics of Principle 2»
https://www.manning.com/books/irresistible-apis
Slide 36
Slide 36 text
Principle 3: Define & Document Use Cases
https://www.manning.com/books/irresistible-apis
Slide 37
Slide 37 text
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
Slide 38
Slide 38 text
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.
Slide 39
Slide 39 text
2. Documentation
+
Slide 40
Slide 40 text
2. Documentation
https://petstore.swagger.io/v2/swagger.json
Slide 41
Slide 41 text
2. Documentation
http://editor.swagger.io/
Slide 42
Slide 42 text
Demo Swagger Editor
Slide 43
Slide 43 text
Code Generation
http://NSwag.org
Slide 44
Slide 44 text
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.
Slide 45
Slide 45 text
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
Slide 46
Slide 46 text
The future of REST
Slide 47
Slide 47 text
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/
Slide 48
Slide 48 text
Recap
Slide 49
Slide 49 text
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
Slide 50
Slide 50 text
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
Slide 51
Slide 51 text
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
Slide 52
Slide 52 text
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/