Roundup Tracker - Issues

Issue 2551237

classification
Adding structured API error messages
Type: rfe Severity: minor
Components: API Versions:
process
Status: new
:
: : rouilj
Priority: low : Effort-Medium, StarterTicket, rest

Created on 2022-11-03 02:07 by rouilj, last changed 2024-09-16 16:16 by rouilj.

Messages
msg7656 Author: [hidden] (rouilj) Date: 2022-11-03 02:07
Problem Details for HTTP APIs: https://www.rfc-editor.org/rfc/rfc7807
details the shape of a json response for an error API return value.

example return:

   HTTP/1.1 403 Forbidden
   Content-Type: application/problem+json
   Content-Language: en

   {
    "type": "https://example.com/probs/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "Your current balance is 30, but that costs 50.",
    "instance": "/account/12345/msgs/abc",
    "balance": 30,
    "status":  403,
    "accounts": ["/account/12345",
                 "/account/67890"]
   }


We already supply the status property.

We also have msg property that probably maps to the title property. The title property can be 
localized.

Type is the unique key for this type of error. The title property can be localized so
can't be used as the key. This URL could map to a document on the roundup web site
with more detailed info about the error, but as a key just needs to be unique if not
resolvable.

Instance probably maps the the url that triggered the error.

rfc7807 does allow extensions to the json format, so the msg property can remain
for backwards compatibility.

However we wrap the object with an error object:

   {
    "error": {
        "status": 404,
        "msg": "Nothing matches the given URI"
    }
}

so the wrapper may need to be removed at some point. Probably in v2 of the rest interface.

Further reading:

  https://dev.to/apisix/structured-error-messages-for-http-apis-lao
msg7657 Author: [hidden] (rouilj) Date: 2022-11-03 02:29
Note that https://jsonapi.org/format/ expects the errors wrapper with an array of error
objects. Always nice to have multiple standards....
msg7917 Author: [hidden] (rouilj) Date: 2023-12-25 17:46
Update for rfc7807 is https://www.rfc-editor.org/rfc/rfc9457.html
msg8124 Author: [hidden] (rouilj) Date: 2024-09-16 16:16
Also see: https://httptoolkit.com/blog/designing-api-errors/ for a nice set of examples.
History
Date User Action Args
2024-09-16 16:16:44rouiljsetmessages: + msg8124
2023-12-25 17:46:26rouiljsetmessages: + msg7917
2022-11-25 05:18:17rouiljsettitle: Adding structure API error messages -> Adding structured API error messages
2022-11-03 02:29:33rouiljsetmessages: + msg7657
2022-11-03 02:07:23rouiljcreate