handle api deprecation

[jeremyletang]

In a near future we may need to deprecate some version of the api. We have to decide of an http response to notify the borg user of a future deprecation of the api and possibly an api which is non available anymore. This may required updating api response with something like: valid response

{
    "status": "OK",
    "data": {/* data response */}
}

valid response with deprecation warning

{
    "warning": "this api version is deprecated and stop working the 31 december 2016, please update borg",
    "status": "OK",
    "data": {/* data response */}
}

error response for an api not available anymore

{
    "status": "ERROR",
    "error": "you tried to use a version of the api wich is not anymore available, please update borg."
}

[crufter]

Should we use error codes perhaps?

[jeremyletang]

why not, I just wanted to make at least deprecation a special case that we can catch in a high level way.

[crufter]

http://stackoverflow.com/questions/13884141/convention-for-http-response-header-to-notify-clients-of-deprecated-api

Seems like status codes are fine for already deprecated APIs but not ones which are 'soon to be deprecated', but you are talking about the former, right?

[crufter]

Closing this, since the borg api already handles this