The document discusses Representational State Transfer (REST), an architectural style for distributed hypermedia systems. It describes the key building blocks of REST including HTTP, URIs, URLs, request methods (GET, POST, PUT, PATCH, DELETE), and status codes. Examples are provided to illustrate how REST can be used to retrieve a resource count, schedule a task to reset a temperature sensor, and return appropriate status codes as the task is processed and completed. The importance of hypermedia and HATEOAS for developing mature RESTful APIs is highlighted.

1. REST in good!
André Goliath

2. [skip motivation, because REST]

3. REST is an abbreviation for…
a) Really Strange Topic
b) Relational Enterprise Scheme Trade
c) Representational State Transfer
d) ??? [use “send a comment”]

4. Representational State Transfer

6. Building Blocks: HTTP
(as far as this talk is concerned,
HTTP and HTTP/2 are the same)

7. URIs (Uniform Resource Identifier)
vs.
URLs (Uniform Resource Locator)

8. URLs locate resources
(“something that we can talk about
and that has ‘properties’ ”)

9. Verbs or methods
operate on resources

10. safe idempotent
GET
HEAD
OPTIONS
PUT
PATCH
DELETE
POST

11. HEAD and GET are the same,
except HEAD not sending the actual body

12. Browsers use OPTIONS to implement
Cross-Origin Resource Sharing (CORS)

13. OPTIONS and CORS Preflights

14. Use PUT to create or replace resources
if you know their exact URL
Otherwise, POST to the parent resource

15. Use PUT to replace a whole resource at once,
PUT operations must be idempotent!
Use PATCH to update partial data

16. We have a list of items, e.g. /messages
How do we get the number of all messages?
a) GET /messages and {…count: 5…}
b) GET /messages/count
c) GET /messages?count
d) ??? [use “send a comment”]

17. We have a list of items, e.g. /messages
How do we get the number of all messages?
> HEAD /messages
< …
< X-COUNT: 5

18. We GET the current temperature from
/house/livingroom/temp. But the sensor is
kinda unstable and needs to be power-cycled
from time to time. How would you do it?
a) POST /house/livingroom/temp/reset
b) PUT /house/livingroom/temp/reset
c) DELETE /house/livingroom/temp
d) ??? [use “send a comment”]

19. We GET the current temperature from
/house/livingroom/temp. But the sensor is
kinda unstable and needs to be power-cycled
from time to time. How would you do it?
> POST /house/scheduledTasks
> {
> time: ‘now’,
> action: ‘reset’,
> target: ‘livingroom/temp’
> }

20. HTTP is kinda bad
for long-running processes
No, you´re just
using it wrong

21. > POST /house/scheduledTasks
> {
> time: ‘in 2 hours’,
> action: ‘reset’,
> target: ‘livingroom/temp’
> }

22. > POST /house/scheduledTasks
> {
> time: ‘in 2 hours’,
> action: ‘reset’,
> target: ‘livingroom/temp’
> }
< HTTP/1.1 201 Created
< Location: https://…/scheduledTasks/7dhe9u

23. < HTTP/1.1 201 Created
< Location: https://…/scheduledTasks/7dhe9u
> GET /house/scheduledTasks/7dhe9u
< Cache-Control "max-age=3600, must-revalidate"
< {
< time: ‘2017-11-10T13:15:28+02:00’,
< action: ‘reset’,
< target: ‘livingroom/temp’,
< status: ‘scheduled’
< }

24. … two hours later …

25. > GET /house/scheduledTasks/7dhe9u
< {
< time: ‘2017-11-10T13:15:32+02:00’,
< action: ‘reset’,
< target: ‘livingroom/temp’,
< status: ‘done’,
< result: 200
< }

26. … one eternity later …

27. > GET /house/scheduledTasks/7dhe9u
< HTTP/1.1 404 Not Found

28. > GET /house/scheduledTasks/7dhe9u
< ???
a) 404 – Not Found
b) 202 - Accepted
c) 204 – No Content
d) 410 – Gone
e) ??? [use “send a comment”]

29. > GET /house/scheduledTasks/7dhe9u
< HTTP/1.1 410 Gone
> GET /house/scheduledTasks/1234567890
< HTTP/1.1 404 Not Found

30. HTTP
Status Codes
(just RTFM)

31. Why 404 has no ‘double meaning’
> GET /house/scheduledTasks/1234567890
< HTTP/1.1 404 Not Found
> GET /house/scheduledTasks/7dhe9u
< HTTP/1.1 410 Gone
> GET /house/scheduledTasks/8fks3k
< HTTP/1.1 200 OK
> GET /house/scheduledTasks/9edm4d
< HTTP/1.1 200 OK

32. Why 404 has no ‘double meaning’
> GET /houes/scheduledTasks/1234567890
< HTTP/1.1 404 Not Found
> GET /houes/scheduledTasks/7dhe9u
< HTTP/1.1 404 Not Found
> GET /houes/scheduledTasks/8fks3k
< HTTP/1.1 404 Not Found
> GET /houes/scheduledTasks/9edm4d
< HTTP/1.1 404 Not Found

33. Level Up your API!

34. The Richardson Maturity Model
https://martinfowler.com/articles/richardsonMaturityModel.html

35. Hypertext as the Engine of Application State
(HATEOAS)
https://github.com/farrelmr/introtospringdatarest

36. Thank You!
André Goliath
Lead Developer
andre.goliath@senacor.de