Recommendation
API clients should develop a user-centric UX to support administrative users in order to reduce the number of errors and equip LEA staff with the tools to solve those errors. API clients should also react intelligently to common error situations to reduce the confusion of LEA stewards.
Reasoning
The UX and the API client behavior has a substantial impact on the efficiency with which LEAs are able to resolve errors.
In particular, LEAs can become overburdened by very large numbers of error messages, many of which can be addressed by small improvements to error handling in the UX.
Further, API clients that are not inspecting error behavior and reacting appropriately can continue to drive unnecessary API transactions and generate even more errors that degrade the experience of LEA IT staff.
Implementation
During API synchronization, use exponential back off when receiving non-Ed-Fi errors from an Ed-Fi API (e.g., HTTP/S 500s; request time outs)
During synchronization, demonstrate the API client does not send multiple dependency order children POST/PUT requests to an API if the parent entity already failed or is missing.
For any failed transactions, provide the LEA’s administrative user a view of the JSON document that was submitted.