Agency error and bulk responses

[thekaveman]

Agency error and bulk responses

[marie-x]

I'll schedule time with @avatarneil to discuss this morning (Tue 2 May)

[schnuerle]

Hi @marie-x and @avatarneil do you have some thoughts on this you can share today?

[thekaveman]

Here's what I came up with for errors needing Bulk Responses, I'm implementing in the OpenAPI as a starting point but we can always adjust if needed:

Sorted by endpoint

Endpoint	HTTP method	Error key	Error description	HTTP code
/event	POST	bad_param	A validation error occurred	400
/event	POST	missing_param	A required parameter is missing	400
/event	POST	unregistered	This device_id is unregistered	404
/reports	POST	bad_param	A validation error occurred	400
/stops	POST	already_registered	A stop with stop_id is already registered	409
/stops	POST	bad_param	A validation error occurred	400
/stops	POST	missing_param	A required parameter is missing	400
/stops	PUT	bad_param	A validation error occurred	400
/stops	PUT	missing_param	A required parameter is missing	400
/stops	PUT	unregistered	This stop_id is unregistered	404
/telemetry	POST	bad_param	A validation error occurred	400
/telemetry	POST	missing_param	A required parameter is missing	400
/telemetry	POST	unregistered	This device_id is unregistered	404
/trips	POST	bad_param	A validation error occurred	400
/trips	POST	missing_param	A required parameter is missing	400
/trips	POST	unregistered	This device_id is unregistered	404
/vehicles	POST	already_registered	A vehicle with device_id is already registered	409
/vehicles	POST	bad_param	A validation error occurred	400
/vehicles	POST	missing_param	A required parameter is missing	400
/vehicles	PUT	bad_param	A validation error occurred	400
/vehicles	PUT	unregistered	This device_id is unregistered	404

Sorted by Error key

Endpoint	HTTP method	Error key	Error description	HTTP code
/stops	POST	already_registered	A stop with stop_id is already registered	409
/vehicles	POST	already_registered	A vehicle with device_id is already registered	409
/event	POST	bad_param	A validation error occurred	400
/reports	POST	bad_param	A validation error occurred	400
/stops	POST	bad_param	A validation error occurred	400
/stops	PUT	bad_param	A validation error occurred	400
/telemetry	POST	bad_param	A validation error occurred	400
/trips	POST	bad_param	A validation error occurred	400
/vehicles	POST	bad_param	A validation error occurred	400
/vehicles	PUT	bad_param	A validation error occurred	400
/event	POST	missing_param	A required parameter is missing	400
/stops	POST	missing_param	A required parameter is missing	400
/stops	PUT	missing_param	A required parameter is missing	400
/telemetry	POST	missing_param	A required parameter is missing	400
/trips	POST	missing_param	A required parameter is missing	400
/vehicles	POST	missing_param	A required parameter is missing	400
/event	POST	unregistered	This device_id is unregistered	404
/stops	PUT	unregistered	This stop_id is unregistered	404
/telemetry	POST	unregistered	This device_id is unregistered	404
/trips	POST	unregistered	This device_id is unregistered	404
/vehicles	PUT	unregistered	This device_id is unregistered	404

[thekaveman]

I think the final question on this is for 500 -- should that really be a text/plain response, or should that be application/json with the body of the single-error response?

{
  "error": "...",
  "error_description": "...",
  "error_details": ["...", "..."]
}

[schnuerle]

I've made a pass across all APIs to align each endpoint to the responses listed in this comment and in the current OpenAPI and Stoplight docs.

Take a look at the release branch to confirm. Example of how I documented it - see the 'Responses' header.

I did not address the 500 question yet. I could go either way on this so welcome feedback @thekaveman @marie-x @avatarneil If it's a quick easy change to OpenAPI (and we think it's a good idea) let's do it today. For MDS spec it's easy now and just changing one line here.

[marie-x]

application/json I'd say

[thekaveman]

It sounds like would want to update the 500 response across all OpenAPI docs then. I'll work on this this morning and get back to this thread.

[thekaveman]

Fixed the 500 response type/schema across all OpenAPI endpoints in openmobilityfoundation/mds-openapi#37

[thekaveman]

I think this issue can be closed after the one-line update in the spec around 500 response type.

[marie-x]

Nice! Thanks!

[schnuerle]

Alright updated the language here: 0018992 (and then fixed "a" to "an").