otsukare Thoughts after a day of work

REST and HTTP - Information not actions

A few days ago, I stumbled upon a blog post by Tom Insam about REST. He is expressing some opinions (and/or disbelief) about REST. These are questions I have often read and my reactions has always been the same: "Why is it so hard for people to think about messages?" HTTP is about communicating information in between a server and a client. It is not about doing actions. These messages will definitely create actions, but these actions in my way of thinking about it are not part of HTTP. With HTTP, I do not say "I buy this product", but I communicate to the server an information that will be treated as an order for buying this product. This is different. Very different. David Larlet pointed to another blog post with the appropriate title: Nobody Understands REST or HTTP. Part of his blog post is specifically to remove the actions from URIs such as

http://example.org/post/show/1

which should be indeed

http://example.org/post/1

But going back to Tom Insam blog's post, I sent him an email about what I thought could be some answers to his 3 questions.

I take HTTP as just a simple way of exchanging messages. and I make a difference between messages and actions.

messages != actions

There is a server and client, and you send messages which will modify the information space not the product. This information space is driven by a contract in between the client and the server and it is why there are so many ways of designing the same service.

About pagination

http://example.org/books/ \ what this URI means is not driven by a query on the server or an absolute answer. It is driven by you. What do you decide it will mean? It can be indeed 1 million books (and you know in your context it makes sense because you are in an environment where you can really deliver a ressource with the record of 1 million books), but it can also be the first 10 books, because you have defined it like this.

http://example.org/books/

then the pagination is also a definition of your own.

http://example.org/books/?start=1&end=200

and you will have to define what 1 to 200 means it could be index of books, it could be pages of list of books.

What I find interesting with pagination is how many services make it not really easy for users. Imagine a service adding photos and showing the last one at the top of the list. (reverse time order) and then paginating. The first time you publish a photo, Pic1, it got the page number one.

GET http://example.org/photos/1

then next photo Pic2

Pic1 moved to http://example.org/photos/2
Pic2 got http://example.org/photos/1

The URIs are not stable, instead of doing the opposite and making the first page last

GET http://example.org/photos/last

and then the next page after last being the highest index N and then decreasing until 1

GET http://example.org/photos/N

Again what links mean is entirely your choice. Though there are a few things which are mostly agreed upon on. See RFC5988 and rel-values

But the real meaning is the one you defined for the application, the same way than any application. There is no universal client able to understand everything on earth. And that’s good. :) So yes in practice you need to document. smile the same way in between human, you have documented practices for exchanging messages.

Am I allowed to make verbs up?

hehe. Addressing the wrong resource smile When you say this book or article is offensive. You are saying something about a book. You do not change what the concept of a book is. So let’s say the book has the URI

GET http://example.org/book1234

And you find the content of the book is offensive. It means 1st that the person, who created the service, agreed to receive messages in this information space which was about the quality of books. It also means it doesn’t have to be on the same service. smile

GET http://example.net/bookquality

returns a form to express the bookquality The meaning of this URI is just that, the entry point for this

POST http://example.net/bookquality?bookid=book1234&nature=offensive

will store a variable that modify in the information space your opinion about the book. Do you want to have access to this opinion for each book. Why not? so you create a URI for this piece of information

GET http://example.org/book1234/nature

what this URI returns could have for meaning, the list of all opinions ever, just your opinion, etc. It really depends on how you design the service.

To conclude: The most important is that you exchange messages to modify/understand the information space. What is happening on the server has nothing to do with HTTP.

I do not claim that I know better. It is just the way I seet it.