13644
Reporter: bko
Type: Improvement
Summary: Maintenance notice in JSON
Priority: Minor
Status: Open
Created: 2013-08-26 13:26:24.181
Updated: 2014-01-13 12:10:02.869
Description: While we deploy the new version of portal, regular users will see a page informing the maintenance status. It would be good that for calls to api.gbif.org we return a JSON response with appropriate http headers for external applications to act accordingly.
For example, it could be:
{
"error": "Service not available due to maintenance. Sorry for the inconvenience."
}]]>
Author: mdoering@gbif.org
Comment: if your client expects something totally different this will still entirely break your json application. It seems to me the same as returning html - both can only be interpreted by humans
Created: 2013-08-29 15:47:08.442
Updated: 2013-08-29 15:47:08.442
Author: bko@gbif.org
Created: 2013-08-29 15:57:05.658
Updated: 2013-08-29 15:57:05.658
I think we should provide certain format and we be consistent about it. This will allow the client application act accordingly.
I am suggesting something like this: http://apidocs.mendeley.com/home/responses-and-errors-1. This for example give me the opportunity to inform users of my module what happened if some features don't work.
Author: mdoering@gbif.org
Comment: you mean we should return good http error codes? I think the varnish response does give a 503 actually, so onError should be fired in ajax calls
Created: 2013-08-29 16:13:20.044
Updated: 2013-08-29 16:13:20.044
Author: mdoering@gbif.org
Comment: Varnsih does return an http 503 error, see attached screen
Created: 2013-08-29 16:15:20.159
Updated: 2013-08-29 16:15:20.159
Author: bko@gbif.org
Comment: That is good. But I mean for accessing api.gbif.org I believe developers usually don't expect to parse an html page. Mendeley has an error message in json which the client app can take and let the user know - I only need to copy that and echo on my web page, users know precisely who and what to blame. So I am just suggesting we make life just a bit easier for developers who use our APIs. This is just a 'nice-to-have' improvement .
Created: 2013-08-29 16:25:03.891
Updated: 2013-08-29 16:25:03.891
Author: kbraak@gbif.org
Comment: [~mdoering@gbif.org] can we please close this?
Created: 2014-01-08 12:30:25.244
Updated: 2014-01-08 12:30:25.244
Author: mdoering@gbif.org
Comment: [~kbraak@gbif.org] gotta ask Burke. Its not done, but I don't need it and would be happy to close it as wontfix
Created: 2014-01-08 13:48:05.645
Updated: 2014-01-08 13:48:05.645
Author: bko@gbif.org
Created: 2014-01-13 12:10:02.869
Updated: 2014-01-13 12:10:02.869
I think it's enough for a 3rd-party developer to detect 503 and inform his/her user of service down time. However, I am still thinking if we in the future will provide detailed messages than just say it's not available. If so, then putting it in JSON format will allow client app use the message/reasoning from the source service, which is us. This in my opinion will help improve end user and developer satisfaction.
If you both of you consider this is good to have, then I suggest we keep it open. It's not urgent after all. Or I am happy to close it as won't fix.
