RESTfull implementation and general informatino

Question

I have been reading a lot lately, and even more experimenting with web Development. There are some things that I simply cant understand, therefore any help is appreciated.

I am not trying to get my homework done for me. I have some holes in my knowledge, that I desire to fill. Please, help me out with your views :)

REST questions: Reading documentation this is perfectly understandable (NODE.JS / Express) example:

EXAMPLE ONE (get):

app.get('/', function(req, res) {
    res.send('please select a collection, e.g., /collections/messages')
})

My explanation: When the root of the server is hit, send thie following message

EXAMPLE TWO (get):

app.get('/collections/:collectionName/:id', function(req, res) {
    req.collection.findOne({name: req.collection.id(req.params.id)},
        function(e, result){
        if (e) return next(e)
        res.send(result)
    })
})

My explanation: When the url in hit, take id from the URL (that is located in params.id) and make search based on it (that is MongoDB).

EXAMPLE THREE (post):

app.post('/collections/:collectionName', function(req, res) {
    req.collection.insert(req.body, {}, function(e, results){
        if (e) return next(e)
        res.send(results)
    })
})

My explanation: When the URL is hit, take the payload(JSON in this case) that is located in req.body, and insert it as a new document.

Questions:

1. Are example one and two both RESTfull?

2. I am now totally confused with params.id. I do understand that POST is transmitted in rew.body... what is params.id? Is it containing URL variables, such as :ID?

3. My explanations... are they correct?

4. Example three is also REST, regardless of the fact that POST is used?

5. Example three, '/collections/:collectionName. Why is the ':collectionName' passed in URL, I could have placed it in req.body as a parameter (along with new data) and take it from there? What is the benefit of doing it?

Thank you

Answer 1

1. An API must be using HATEOAS to be RESTful. On first example, if / is the entry point of your API, the response should contain links for the available collections, not a human readable string like that. That's definitely not RESTful.

2. Exactly.

3. They're OK, except that there's nothing in the third example implying it's a JSON body. It should check for a Content-Type header sent by the client.

4. REST isn't dependent on HTTP. As long as you're using the HTTP methods as they were standardized, it's fine. POST is the method to use for any action that isn't standardized, so it's fine to use POST for anything, if there isn't a method specific for that. For instance, it's not correct to use POST for retrieval, but it's fine to use it for creating a new resource if you don't have the full representation.

5. POST means the data body is subordinated to the resource at the target URI. If collectionName were in the POST body, this would mean you were POSTing to /collections, which would make more sense to create a new collection, not a new item of a collection.