HTTP status codes review

[remyla]

review the HTTP status codes used by the operations of our RESTful server.

• find the HTTP status codes which suit best for each response
• provide a homogeneous way to return errors and successes
• write the inline doc in routes
• find a markdown syntax to write this documentation in the Wiki (the reference so far is the syntax used in the create method https://github.com/remyla/damas-core/wiki/API#apicreate) UPDATE: as @gnoxr suggests below, a new "Contributing" page in the wiki is a good idea to contain this syntax for each operation

Note: the resulting status codes should be reported in the client implementations (damas.py damas.js) and in the tests

@gnoxr

[gnoxr]

The possible error codes have been documented in this commit.

[gnoxr]

The best way to provide the right status code is to know what actually happened.

Currently, the database engine works like this:

callback(false, data); // On success
callback(true); // On error, the second parameter being undefined or null

A good way to provide explicit errors to the callback would be to use integers. It is how most programs work, even the HTTP codes in fact.

callback(0, data); // On success, as 0 evaluates to false it is compatible with existing code
callback(n, details); // On error, n being a code and details debug information

In order not to duplicate code in every database function, we could provide a sendCode(), getError() or whatever() method, which would be used this way:

self.sendCode(err, data, callback); // "err" being the error provided by the database driver

The question is, what codes should we call the callback with?

1. HTTP status codes: we simplify greatly the callback work (directly use whatever the database sent) and have a standardized support, however we lose the unique responsibility principle.
2. Our own status codes: we need more work, but the database is HTTP-agnostic.

We could cheat by having our own status codes coincide with the HTTP statuses, with the "0" exception to tell that everything worked fine instead of 2xx statuses. It is just another way to present the first solution.

[remyla]

Thank you for this enlightenment.

It will be important to finegrain the returned errors at one point, certainly when the number of features will increase. For now I would keep it for later since we have other important subjects to adress

[zankia]

The API reference on the wiki has been updated by @gnoxr but it doesn't seem to be finished and there is no syntax rule at all. Il could be easier to define a way of writing HTTP statuses on wiki and by extension every command

[remyla]

yes the description of the http queries and responses in the wiki page could be updated in a nicer normalized way.

(My bad, that i didn't write it well the first time ;)

we could use the syntax used for the create, read and update operations which is nicest. I reopen

[gnoxr]

About the wiki documentation, I wanted to raise the point that the miscellaneous HTTP status codes are not shown outside of the libraries.
I mean, perhaps these codes should be put in the "Contributing" page, in a new section about implementing a new library, which is in my opinion more accurate and allows to lighten the API reference page.

What do you think?

[remyla]

I agree. This totally make sense. I update the issue description

[remyla]

The HTTP status codes are now described in the Contributing page under the «Protocol Specifications» chapter.

closing this issue.