I was putting my notes together from class about REST APIs to help someone out, but I found out I misunderstood what they needed help with before I finished but after I had written all this so here, enjoy, maybe you'll learn something.
Measuring RESTfulness and creating a HATEOAS REST service.
When you measure RESTfulness we have a scale that’s called Richardson Maturity Model. The scale ranges from 0-3 where 0 is not RESTful and 3 is HATEOAS.
0 on the scale of the RMM is a simple URI with the method in the request. This is the level SOAP is at. It’s not restful.
1 on the RMM scale is when you’re dividing the URIs on a resource level, instead of the URI /API/getAllTheThings we now split the things up in the URI not in the request body; /API/things/thingid, however, we’re still putting the request method in the request body.
2 of the RMM scale is when you’re on top of dividing your URIs on a resource level start using the HTTP protocol’s GET, POST, PUT and DELETE and the appropriate response codes:
100 - Continue
200 OK (it’s common practice to add the text OK to the responsecode) - Everything went well.
404 - File Not Found
418 - I’m a Teapot (and I can’t brew coffee)
500 - Internal Server Error
Pretty much the
- 100 codes are informative,
- 200 codes are success codes,
- 300 codes are for redirects,
- 400 codes are user/client errors and
- 500 are internal server error.
Read more about the different responsecodes at https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
3 is when you Reach HATEOAS and is the last on the RMM scale. You’re done, your webservice is - in theory - the best thing ever. Have a cup of coffee and high five your colleagues (or cat) and everyone who’s ever gonna use it.
So what is HATEOAS?
HATEOAS stands for:
Hypermedia - You had better look this up; hypermedia, hypertext and the other hypers are by legacy all the hype!
as
the
Engine
of
Application
State
To crudely sum it up; media (text, images, video, audio) is what’s supposed to drive the interaction between the client and server. The idea is to let a client know how to interact with your API without any manual or prior knowledge about the API. Just like how it works when you’re visiting a web GUI; you don’t need to know what URLs will take you to the next part of the website to go there, there’s a link, you click it and you’re there! Click here for free pictures of kittens!
Here’s a non HATEOAS JSON response from the API at the URL /API/messages/17
{“ID”: 17,“message”: “I love pie.”,“created”: “2015-10-12T10:25:00.000”,“author”: “25”}
That’s the object of information that I wish to retrieve. But it really doesn’t say anything about the rest of the API.
This is a response from an API qualifying for HATEOAS:
{“ID”: 17,“message”: “I love pie.”,“created”: “2015-10-12T10:25:00.000”,“author”: “25”,“links”: [{“href”: “/API/messages/17”,“rel”: “self”},{“href”: “/API/messages/17/comments”,“rel”: “comments”},{“href”: “/API/profiles/25”,“rel”: “author”}]}
This response offers the information the client/user need to orient themselves while using the API.
But wait, there’s more!
Let’s say we’ve been good devs and made an API with a URI to the messages, the individual resource of a message, the profiles, the profile of the author, the comments and the individual comment like so:
/API/messages/
/API/messages/{nn}
/API/messages/{nn}
/API/messages/{nn}/comments/
/API/messages/{nn}/comments/{nn}
/API/profiles/
/API/profiles/{nn}
Of course all of these maps back to the resources and objects in the code. How would we do with them HTTP methods in the requests?
/API/messages/ is the URI
