Mixed JSON and CBOR is annoying for clients

[JAG-UK]

In trying to build a new ground-up Python implementation of SCRAPI I am finding it quite difficult to cope with commands that might return JSON or might return CBOR depending on things like operation or error state. It makes response and error handling code messy and harder to review.

Following discussion in the editors' meeting I propose to make the whole thing COSE/CBOR. This is much more aligned with the architecture and the IETF mission in general.

[henkbirkholz]

No objections from my side. Would EDN play a role in "make the whole thing COSE/CBOR"?

[JAG-UK]

Would EDN play a role in "make the whole thing COSE/CBOR"?

It certainly could! How would you like to see the Problem Details object represented, for example, if we did this way?

Note SCRAPI is not a CoAP API so I din't really want to use RFC 9290. I want to take advantage of the 'Other Formats' provision of Appendix C of RFC 9457 and return Content-Type: application/problem+cbor

So the original JSON is:

{
  "type": "urn:ietf:params:scitt:error:badSignatureAlgorithm",
  "detail": "Signing algorithm 'WalnutDSA' not supported."
}

And I think we'd want to see something like this but in much nicer EDN:

a4                                      # map(4)
   0x64                                 # text(4)
      0x74797065                        # "type"
   0x78 28                              # text(40)
      0x68747470733a2f2f6578616d706c652e636f6d2f6572726f722f76616c69646174696f6e2d6572726f72
                                         # "urn:ietf:params:scitt:error:badSignatureAlgorithm"
   0x66                                 # text(6)
      0x64657461696c                    # "detail"
   0x78 20                              # text(32)
      0x4d697373696e67207265717569726564206669656c642027757365726e616d65272e
                                         # "Missing required field 'username'."

[aj-stein]

Following discussion in the editors' meeting I propose to make the whole thing COSE/CBOR. This is much more aligned with the architecture and the IETF mission in general.

I support this change as well, like Henk.

[aj-stein]

How would error code and and HTTP response information work in light of this proposed change, @JAG-UK?

[JAG-UK]

How would error code and and HTTP response information work in light of this proposed change, @JAG-UK?

I'll be putting up a PR for the -121 Hackathon showing this. Essentially:

Error responses MUST be sent with the Content-Type: application/problem+cbor HTTP header.

As an example, submitting a Signed Statement with an unsupported signature algorithm would return a 400 Bad Request status code and an RFC 9290 Concise Problem Details object as the body:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+cbor

{
  / title /         -1: "Bad Signature Algorithm",
  / detail /        -2: "Signed Statement contained an algorithm that is not supported",
  / instance /      -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm",
  / response-code / -4: 400,
}

[aj-stein]

Error responses MUST be sent with the Content-Type: application/problem+cbor HTTP header.

Partly serious, partly in jest, sounds like we may have a need for a RFC for CBOR-based HTTP APIs. 😆

HTTP/1.1 400 Bad Request
Content-Type: application/problem+cbor

{
  / title /         -1: "Bad Signature Algorithm",
  / detail /        -2: "Signed Statement contained an algorithm that is not supported",
  / instance /      -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm",
  / response-code / -4: 400,
}

Is there a reason we are deviating from RFC9457 ever so slightly?

[aj-stein]

And to be clear, I would think response-code over type implies a possible layering concern by bringing HTTP error codes "down into" the API surface of CBOR-based payloads for SCITT, no?

[JAG-UK]

Is there a reason we are deviating from RFC9457 ever so slightly?

Yes. We're following RFC 9290 and that deviated. Note that 9290 is ordinally between 7807 and 9457 so maybe there's an update that needs to happen there.

There are 2 legit options and I think both have their own unique charm. One is to follow 9290, which I showed above. The other would be to exploit Appendix C of 9457.

I considered the latter and it's easy enough to do, I was just trying to favour the documents from the CBOR stable.
The slightly grotty thing about the 9457 route is that we can't use any of the defined CBOR tags so it ends up just being what Pythonistas would call 'derisory dictionary programming' with uncompressed string keys. But we're not CoAP so who cares?

Given the explanation, any strong opinion on those routes?

[JAG-UK]

And to be clear, I would think response-code over type implies a possible layering concern by bringing HTTP error codes "down into" the API surface of CBOR-based payloads for SCITT, no?

Yeah I really flip-flopped on that one. I spoke to one of the CBOR authors and they include the status code in the object is for extra later clues to errors (poring over log files for example) but I agree it's a bit of a violation. It would be very easy to convince me to remove that