REST API returns are plain text for errors, JSON or nothing for successful
Successful requests to the REST API return a 2xx HTTP code to indicate success either with or without JSON data depending on the context of the request.
At least one (I’ve not checked the othes yet) 4xx error returned from the REST API returns a plain text error message rather than a JSON error message.
For example attempting to create a domain that exists returns a 400 error with the response text “Domain exists”.
Do you think this matters? Probably not much but does mean handling valid responses goes down a JSON path and handling error message goes down a plain text path. JSON error messages might arguable have been somewhat more consistent and programmable.
thanks
On Jan 10, 2015, at 03:42 PM, Andrew Stuart wrote:
Successful requests to the REST API return a 2xx HTTP code to indicate success either with or without JSON data depending on the context of the request.
At least one (I’ve not checked the othes yet) 4xx error returned from the REST API returns a plain text error message rather than a JSON error message.
For example attempting to create a domain that exists returns a 400 error with the response text “Domain exists”.
Do you think this matters? Probably not much but does mean handling valid responses goes down a JSON path and handling error message goes down a plain text path. JSON error messages might arguable have been somewhat more consistent and programmable.
Some of this has to do with the historical legacy of the tools we've used to implement the REST API (first, lazr.restful, then restish, and now hopefully finally, falcon). IIRC it wasn't possible to set a JSON body response on error codes in lazr.restful and that just got inherited throughout the other migrations.
I don't know if it matters. I suppose we'll have to see what client authors think. Changing it would be an API change though, so perhaps we'd need to wait until we rev the REST API.
Cheers, -Barry
I don’t think it’s a big deal in the short term because the plain text error message can easily be read from the response.
The only thing that’s somewhat odd is that the content-type is application/json even though the content isn’t (for error messages).
On 11 Jan 2015, at 5:39 am, Barry Warsaw <barry@list.org> wrote:
On Jan 10, 2015, at 03:42 PM, Andrew Stuart wrote:
Successful requests to the REST API return a 2xx HTTP code to indicate success either with or without JSON data depending on the context of the request.
At least one (I’ve not checked the othes yet) 4xx error returned from the REST API returns a plain text error message rather than a JSON error message.
For example attempting to create a domain that exists returns a 400 error with the response text “Domain exists”.
Do you think this matters? Probably not much but does mean handling valid responses goes down a JSON path and handling error message goes down a plain text path. JSON error messages might arguable have been somewhat more consistent and programmable.
Some of this has to do with the historical legacy of the tools we've used to implement the REST API (first, lazr.restful, then restish, and now hopefully finally, falcon). IIRC it wasn't possible to set a JSON body response on error codes in lazr.restful and that just got inherited throughout the other migrations.
I don't know if it matters. I suppose we'll have to see what client authors think. Changing it would be an API change though, so perhaps we'd need to wait until we rev the REST API.
Cheers, -Barry
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
On Jan 11, 2015, at 06:06 AM, Andrew Stuart wrote:
I don’t think it’s a big deal in the short term because the plain text error message can easily be read from the response.
The only thing that’s somewhat odd is that the content-type is application/json even though the content isn’t (for error messages).
That, at least, is a bug. Care to file one?
Cheers, -Barry
Hmmm.
Happy to do so if you like. Would you mind pointing me in the direction of some instructions for filing bugs please?
FWIW I’d probably favor a REST API that is behaving improperly by returning plain text error responses (i.e. the current situation) rather than a REST API that returns application/json content type for valid responses and text/plain for errors. Once that gets baked into release 1 it’ll be challenging to correct back to application/json later because people will write clients to expect text/plain for errors.
It’s a whole lot easier conceptually to deal with a REST API that always returns the same content-type regardless of the outcome of the API call.
Some REST tools don’t have any mechanism for defining mixed response type APIs which leads to some weird outcomes when querying successfully versus getting errors. In short, I’d leave as-is and eventually turn the error text into json, but obviously Barry you should say what you want.
as
On 11 Jan 2015, at 6:10 am, Barry Warsaw <barry@list.org> wrote:
On Jan 11, 2015, at 06:06 AM, Andrew Stuart wrote:
I don’t think it’s a big deal in the short term because the plain text error message can easily be read from the response.
The only thing that’s somewhat odd is that the content-type is application/json even though the content isn’t (for error messages).
That, at least, is a bug. Care to file one?
Cheers, -Barry
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
On Sunday 11 January 2015 12:53 AM, Andrew Stuart wrote:
Hmmm.
Happy to do so if you like. Would you mind pointing me in the direction of some instructions for filing bugs please?
https://bugs.launchpad.net/mailman/3.0/+bugs
-- thanks, Abhilash Raj
On Jan 11, 2015, at 06:23 AM, Andrew Stuart wrote:
Happy to do so if you like. Would you mind pointing me in the direction of some instructions for filing bugs please?
FWIW I’d probably favor a REST API that is behaving improperly by returning plain text error responses (i.e. the current situation) rather than a REST API that returns application/json content type for valid responses and text/plain for errors. Once that gets baked into release 1 it’ll be challenging to correct back to application/json later because people will write clients to expect text/plain for errors.
It’s a whole lot easier conceptually to deal with a REST API that always returns the same content-type regardless of the outcome of the API call.
Some REST tools don’t have any mechanism for defining mixed response type APIs which leads to some weird outcomes when querying successfully versus getting errors. In short, I’d leave as-is and eventually turn the error text into json, but obviously Barry you should say what you want.
I think at least the Content-Type should be accurate.
Your response sounds a little contradictory, but let me see if I can summarize it. From a practicality view point, you prefer the current implementation, even if it isn't conceptually pure, at least for now.
That works for me because then I don't have to worry about changing anything. :) I'm open to re-evaluating that in some future Mailman release.
Cheers, -Barry
Yes I’d favor leave as is, and at some stage in future convert the error messages to JSON.
On 12 Jan 2015, at 12:22 pm, Barry Warsaw <barry@list.org> wrote:
On Jan 11, 2015, at 06:23 AM, Andrew Stuart wrote:
Happy to do so if you like. Would you mind pointing me in the direction of some instructions for filing bugs please?
FWIW I’d probably favor a REST API that is behaving improperly by returning plain text error responses (i.e. the current situation) rather than a REST API that returns application/json content type for valid responses and text/plain for errors. Once that gets baked into release 1 it’ll be challenging to correct back to application/json later because people will write clients to expect text/plain for errors.
It’s a whole lot easier conceptually to deal with a REST API that always returns the same content-type regardless of the outcome of the API call.
Some REST tools don’t have any mechanism for defining mixed response type APIs which leads to some weird outcomes when querying successfully versus getting errors. In short, I’d leave as-is and eventually turn the error text into json, but obviously Barry you should say what you want.
I think at least the Content-Type should be accurate.
Your response sounds a little contradictory, but let me see if I can summarize it. From a practicality view point, you prefer the current implementation, even if it isn't conceptually pure, at least for now.
That works for me because then I don't have to worry about changing anything. :) I'm open to re-evaluating that in some future Mailman release.
Cheers, -Barry
Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40s...
Security Policy: http://wiki.list.org/x/QIA9
participants (3)
-
Abhilash Raj -
Andrew Stuart -
Barry Warsaw