Quick Notes for REST Services

#Roy Thomas Fielding is architect of REST. He is one of the principal author of HTTP specification, an authority on compter network architecture and co-founder if Apache HTTP server project. He was named as ne of the top 100 innovators in the world under age of 35.

#Not a standard but guidelines.

#RESTful services use Resource based URI e.g. weatherapp.com/zipcode/12345 whereas normal HTTP website works on action based URIs e.g. weatherapp.com/weatherlookup.do?zipcode=12345

#Collection URIs – e.g.
GET /messages      // get all messages
DELET /messages/{message-id}/comments       //delete all comments
#HTTP has “methods” or “verbs” that are used to interact with URLs:
GET (Read only method. Can be made any time and doesn’t change the state on server),
POST (Create method – submits something to server),
PUT (Update method – updates something on server),
DELETE (Delete Method – deletes something on server)

Uncommon HTTP methods
HEAD (The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. Used for obtaining metainformation about the entity)
OPTIONS (The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI.)

Example of above methods:
GET …/Profiles/{username}              //Fetches the user data
GET …/Messages/{message-id}       //Fetches the message content

DELETE   …/Messages/{message-id}/comments/{comment-id}
POST     …/Profiles/            //Creates a new profile
PUT      …/Messages/{message-id}/Comments/{comment-id}  //modifies comment data

#METADATA
HTTP status codes are used for communication for any updates from REST services:
1xx   -> Information code
2xx  -> success (201-created, 200-ok, 204-no content)
3xx -> Redirection (301-found, 302-temp redirect, 304-not modifies)
4xx  -> client error codes (400-bad request, 401 – un-authorized, 403-forbidden, 404 –not found)
5xx -> server errors (500 – internal server error etc)

#Idempotent (can be repeated)/Non-Idempotent (cannot be repeated)
GET/PUT/DELETE – are imdempotent so are safe to repeat
POST  – Non idempotent as it changes the state and submits the data so cannot be repeated unless it is intended.

#REST Response
json/xml

HATEOAS (Hypermedia as the engine of application state)
#in normal http communication, hyperlinks are used as a mean to communicate with website. Click on link and you are on next page.
#If we do same kind of work with REST responses, THAT’S what we do here:!!
e.g.
{
“id”:”20”,
“message”:”Hello world”,
“date”:”01jan2015”
“author”:”myself”
“comments URI”: “api/messages/20/comments”
“likes URI”: “api/messages/20/likes”
“shares URI”: “api/messages/20/shares”
“AuthorProfile URI”:”api/profiles/myself”
}

So given these kind of responses, client can perform next operations without asking/knowing/looking other explicit URIs.

#So “hyperlinks” or “hypermedia” present in responses being the driver or “engine” of the “application state” is called HATEOAS

We should use “rel” attribute to define the relation with links in KSON responses.

Richardson maturity model – to judge the level of RESTful API
Level 0 – Plain old xml, Only one URI for all actions, message body contains details.
Level 1 – Individual URIs for each resources, message body still contains all details of operations.
Level2 – Use standard HTTP methods, Right usage of http status codes, idempotent/non-idempotent coniderations.
Level3 – Level 2+HATEOAS

JAX-RS API is used for RESTful web services. Various libs: restlet, resteasy,jersy. Libs Provide all implementation.

Leave a Reply