Three questions about designing REST services

Question

I'm trying to design REST services in a correct way, but encountered a few moments I'm not sure of, but should be pretty common:

For example, I have entity car and I get it by car/{id}. What if I want to have a separate requests for car details (object with a lot of additional properties)? Should it look like car/details/{id} or car/{id}/details?
I want to call some action not from CRUD, like upload or uploadAndProcess. I can't name them directly, since verbs are not allowed in REST. How the request should look like? Something like POST car/{id}/upload/activate or POST car/{id}?upload=true,activate=true?
I've read few articles that says, that it's not allowed to use anything in path variables except ids, and everything else should be sent as request attributes. And the other says, that it's ok to use them for required attributes. Which is true?

Please limit yourself to a single question in your question. That means people can answer it without having to know the answer to you other questions and it makes it easier to find duplicate questions where the answer may already appear. — Quentin, May 23 '16 at 14:51
I thought about it at the beginning, but decided that each of them are too small for a separate question. But maybe you are right. — Mikhail, May 24 '16 at 07:27

score 3 · Answer 1 · answered May 23 '16 at 14:57

ad 1)

From a REST viewpoint, it does not matter. URL patterns are not part of the REST principles.

ad 2)

REST is about Resources. What are the resources behind the methods you want to call? The activation of a car could be modeled as a resource.

Or do you want to manipulate an existing resource? In this case use a POST /car/{id} with the properties you want to change in the request body.

ad 3)

Both are false. REST says nothing about which part of an URL has what meaning. The important thing is that an URL identifies a resource. If the identifiying is done using the path or query parameters does not matter.

score 2 · Answer 2 · edited May 23 '17 at 11:59

You should review Rest In Practice, by Jim Webber.

Short answer to #2: the resources that enable your application protocol are NOT entities in your domain model; they are end points that know how to receive and process documents -- the changes that happen to your domain model are a side effect of the document processing.

HTTP is a CRUD application for documents. So what you want in your RESTful app is to CRUD a document that describes the changes you want applied to your domain model. The document is your command message, the resource you send it to is either a command resource or a command collection resource

As noted by @Display Name, REST doesn't care what spelling you use for your identifiers. You can use hash values for all of your identifiers, and that's OK.

The restrictions you are referencing here actually come from various URI design guidelines. You should follow whatever guidelines are in place for your project. If writing your own, the most important thing would be to make sure that you are consistent with the RFC 3986. Which basically says that hierarchical information belongs in the path, and non hierarchical information doesn't.

You may have missed this older discussion: REST API Best practices: Where to put parameters?

Three questions about designing REST services

2 Answers2