Friday, October 23, 2015

RESTful APIs and RMM

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}/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

No comments:

Post a Comment