How prescriptive should we be about which HTTP error codes to return?

[duglin]

404 is one we do mandate, and we sometimes say it must be a 400, but most of the time we just say "an error must be generated". Do we need to be more precise? Should we standardize the error messages?

[duglin]

Yes and consider using: https://datatracker.ietf.org/doc/html/rfc7807 -> https://datatracker.ietf.org/doc/html/rfc9457

[manuelottlik]

We need to provide a way to standardize the non-happy path in an extensible way.

[duglin]

Proposal:

• Define the http response code for each error - MUST use these
• Define the problem/json for each error - MUST use these if they advertise they support problem/json
• Define a capability so people can advertise if they expose problem/json or not ("not" is for s3-like usecases)
• Impls can add extension attributes to the spec defined problems
• Impls can add extension problems (custom "type") for non-spec-defined error situations
• Add the ability to expose a URL so clients can retrieve the list of errors supports + extensions they support

[duglin]

Need:

• make sure each error has the proper HTTP response code
• make sure each error has the RFC9457 fields (we want to use) defined

[duglin]

@manuelottlik will work on a template to follow for the spec text/ "errors" appendix

[manuelottlik]

This would be a very simple problem for a 404:

{
  "type": "https://docs.xregistry.io/problems/default/not-found-error",
  "instance": "/schemagroups/mygroup/schemas/myschema",
  "title": "Not Found"
}

This could be a more advanced problem that has an additional attribute compatibility in its body to give problem relevant information to the client:

{
  "type": "https://docs.xregistry.io/problems/compatibility-violated",
  "instance": "schemagroups/mygroup/schemas/myschema/versions",
  "title": "Compatibility violated",
  "detail": "Can not create version because it violates the compatibility",
  "compatibility": "forward_transitive"
}

This would be a JSON schema representation we can use in our OpenAPI:

DefaultProblem:
  type: object
  description: default problem object thrown when no further problem is specified
  required:
    - type
    - status
    - title
  properties:
    status:
      type: integer
      format: int32
      description: HTTP status code
      example: 400
    type:
      type: string
      format: url
      description: URI pointing to a human readable documentation
      example: https://docs.xregistry.io/problems/email-already-taken
    title:
      type: string
      description: short, human readable description of the problem
      example: The provided e-mail address is already taken.
    detail:
      type: string
      description: human readable explanation of the problem
      example: The e-mail adress serves as an identifier and thus can only be taken once.
    instance:
      type: string
      description: endpoint where the problem occurred
      example: /users

I copied these things from a personal project of mine and adapted them to xRegistry. The reason for the camelCase titles is i18n, since clients might want to use that.

[duglin]

https://datatracker.ietf.org/doc/html/rfc9457#section-3.1.5

"instance" is kind of interesting. As defined it looks like it's a URL to the "problem json" and not the instance/object that generated the error. So when you used schemagroups/mygroup/schemas/myschema/versions I'm not sure that's correct. However, I would prefer to use it as you're using it... meaning, the "thing that we were processing". Think that's ok?