Design: consistent API responses with validation messages

Description

We need to establish a design for all APIs and all endpoints to follow when providing warning messages about invalid data.

Currently we are seeing some inconsistency in the different API endpoints. Below are examples from memory (may not match actual strings):

1 { 'field.requisition.lineitem[3].quantity': "cannot order quantity bigger than budget allows" }
1 2 3 4 { 'info': "cannot request fewer quantity than quantity on-hand" , 'info': "changes to quantity not allowed when requisition is already approved" }
1 { 'nameOfField': "message" [, optional additional messages] }

BUT this pattern of using field names where the API knows the UI field name would seem to tightly couple the UI to the back-end (bad).

The AngularJS reference UI — and any future UI or other API consumer — will need a consistent format for validation messages to come back in.

Acceptance Criteria

  • Design activities have occurred and we have an agreed-upon pattern for this, with buy-in/approval from the Architect and at least one SolDevelo lead

  • Documented this design pattern in a way developers can understand

  • Update the RAML or API documentation so we explain to API consumers how they can expect to receive these validation errors (maybe we write this RAML change but don't push it to master since at no time do we want the RAML to be out of sync with the working state of the endpoints)

  • File ticket(s) for bringing the current APIs and all v3 endpoints into compliance, and updating the reference UI to match and to still work

Status

Assignee

Brandon Bowersox-Johnson

Reporter

Brandon Bowersox-Johnson

Labels

None

Story Points

5

Epic Link

Sprint

None

Fix versions

Priority

Major