Design Guidelines: HTTP Status Code type should be Integer, not String

[hdamker]

Currently the API Design Guidelines define HTTP Status Code as String within the "proposed json error structure":

{
   "status": "400",
   "code": "INVALID_ARGUMENT",
   "message": "A human readable description of what the event represent"
}

There is a discussion in QualityOnDemand (see here) which came to the conclusion that the type Integer for the HTTP Status Code would be the better solution:

• Easier to use for API consumers (as all HTTP Status Codes are three digit integer between 100 and 599)
• Compliant to RFC 9110 which says: The status code of a response is a three-digit integer code

It would be great if this issue could be addressed short-term in Commonatlities as it is currently blocking the PR Align error format with Commonalities guidelines which itself should be done before other PRs.

---

Further noticed, but not part of this issue:

• The references to RFC 2616 and RFC 7231 in chapter 3.2 of the API Design Guidelines could be replaced by RFC 9110, as they are obsoleted by the newer one.
• Chapters 3.2 (HTTP Response Codes), 6 (Error Responses) and 11.5 (Data Definitions) have overlapping content and are not consistent

[shilpa-padgaonkar]

I agree. As stated in https://httpwg.org/specs/rfc9110.html#rfc.section.15 - status code of a response should be a three-digit integer code.
I would recommend the change as

{
"code": 400,
"status": "INVALID_ARGUMENT",
"message": "A human readable description of what the event represent"
}

If the colleagues currently involved in the discussion for aligning QoD with the Guidelines doc, already create a PR against the doc, it would help speed up this task as it can then be discussed and agreed in the next commonalities call.

[eric-murray]

Agree

[RubenBG7]

Agree, let me change the definition

[RubenBG7]

Issues 145 (API Guidelines) and 146 (CAMARA_common.json ModelError Property) with docs changes applied.

[hdamker]

Issue is resolved with #145 and #146

[RubenBG7]

Changes added on #149 to delete string patter due to change to integer, and #150 fixed some bad words and format in github view