API documentation for API v1 #491
Conversation
korelstar
added
the
feature: API
| - when sending a request which uses a feature that wasn't available from beginning of the used major version, the client has to cope with the situation that the server ignores parts of the request | ||
| - when processing the JSON response, the server may ommit fields that where not available from beginning of the used major version | ||
|
|
||
| If a client requires a certain feature, it should check the `X-Notes-API-Versions` HTTP header of the server response. |
There was a problem hiding this comment.
Should we also send a special HTTP header for the full API version used in the current request/response? Example: a client requests /index.php/apps/notes/api/v1/notes and wants to know if a specific minor version is supported by the server (e.g. because that version introduced a new feature). Currently, the client has to check the X-Notes-API-Versions HTTP header from the response (which could be, e.g., 0.2, 1.1), search for the major version 1 and look at the minor version.
In order to ease this check, we could add another X-Notes-API-Version (singular!) HTTP header which contains the currently used API version only, e.g. 1.1.
@nextcloud/notes @stefan-niedermann
There was a problem hiding this comment.
I thought about it. I technically don't need it, but it might be quiet useful for debugging and/or logging.
On the other hand: If we add many headers which aren't actually needed i am worrying about the traffic we are causing. We did so much work with the ETags and If-Modified-Since-stuff to drastically reduce the size of the responses and speed up everything and now we are adding many "long" headers which aren't necessarily needed.
Maybe a better option would be the possibility for the client to explicitely set a debug-header. If set, the server can add such kind of information (and maybe even set the server level for the context of the request to a more sensitive level)?
What do you think about this approach?
There was a problem hiding this comment.
I think the client should not be able to set the debug level - for security reasons. But we could check if server debug mode is active and send some debug information then. E.g, exact message and stack trace in case of an exception. What's about that?
There was a problem hiding this comment.
Sounds even better, but the stacktrace would have to be in the body, no? That might change the expection of the response...
I would start with "If server is in debug mode, attach the X-Notes-API-Version header as you proposed.
Seems to be an easy compromise.
The API documentation is moved from the wiki to the main repository.