Modeling REST Services Part 1- What is REST

Over the last couple of years, a fellow engineer Marko and I have discussed different use cases around modeling REST services. Some of the cases have been quite simple to model while others seemed a little off or not in sync with the rest. I believe one of the reasons for this was due to us not setting up simple guidelines upfront. He suggested that one of my first blog entries cover this subject. I thought it was a great idea. Feel free to make recommendations or provide feedback.

What is a REST service?

I will try to keep my definition of REST brief. REST has been around for over a decade so there are quite a few detailed articles on the web describing what REST is. I am sure I will add a few other tidbits but for the most part, I want this article to primarily address concerns on modeling the REST service interface and semantics around accessing the resources provided.

REST stands for Representational State Transfer. It is not a framework but rather an architectural style of creating web services. REST was first introduced by Roy Fielding in 2000 as part of a dissertation he wrote on “Architectural Styles and the Design of Network-based Software Architecture”. For an in-depth study, a copy of the dissertation can be found at the following site. Fielding’s Dissertation. I would also recommend you check out Martin Fowler’s description of the Richardson’s Maturity Model.

REST services primarily are implemented throughout the industry using the HTTP protocol. An HTTP RESTful service consists of resources (nouns) that are accessed using CRUD methods (verbs) that are part of the protocol. A given resource’s URI (Universal Resource Identifier) is used along with the HTTP methods to Create, Read, Update, or Delete the resource.

“REST is NOT RPC over HTTP” Rant

REST has often been confused with “RPC over HTTP”. Here are example URIs for an RPC-like service taken from a widely known site. This is often mistaken for and is similar to REST but by definition does not follow the REST style of architecture. The service is a great service but not a good example of REST.

Uploading Photo (in context of the other URI on the site, upload is a verb, not a noun)

https://up.famous-photo-site.com/services/upload/

Replacing Photo

https://up.famous-photo-site.com/services/replace/

Example calling echo test

https://api.famous-photo-site.com/services/rest/?method=site.test.echo&name=value 

Notice how each URI does not point to a resource but rather identifies an action or method. This is not the same as using a URI to access a resource. It appears to be modeled after a service’s remote procedures or processes (verbs) and not resources (objects, nouns)

The following is the same service above modeled following the REST style of architecture.

Uploading Photo (using HTTP Action: POST)

https://up.famous-photo-site.com/picture-service/pictures/

Replacing Photo (using HTTP Action: PUT)

https://up.famous-photo-site.com/picture-service/pictures/{picture ID to update/replace}

Retrieve Photo (using HTTP Action: GET)

https://up.famous-photo-site.com/picture-service/pictures/{picture ID to retrieve}

Delete Photo (using HTTP Action: DELETE)

https://up.famous-photo-site.com/picture-service/pictures/{picture ID to delete}

REST Example to create an echo test process (using HTTP Action: POST)

https://up.famous-photo-site.com/service/echo-tests

The original echo-test RPC-like call had a query parameter called name. This REST example assumes name is a property of the echo-test and not a key to a particular echo-test. It would be passed in the echo-test body to be posted for creating the resource. An echo test process is created and the business ID of the process is returned. You can check the status of the process or results using an HTTP Action: GET with the ID.

https://up.famous-photo-site.com/service/echo-tests/{job-id}

 

Modeling a REST Service Part 2 – Basics

 

Leave a Reply