problem type identifiers

Scope

Decide on recommendations for problem type identifiers: absolute URLs, relative URLs, URNs or other solution.

Requirements

requirement	explanation
stable identifier unchanging over time identical across all environments (test, acpt, prod)	error handling in client code e.g. decide how to handle error depending on problem type statistics based on problem type
2. find documentation page on problem type (if provided)	URL present, can be rewritten for reverse proxy e.g. routing https://myinternaldomain.org/rest/myApi/v1/refData/problems/myProblemType ⇒ https://externaldomain.com/myApi/v1/refData/problems/myProblemType
3a. Problem RFC standard compliance	A URI reference [RFC3986] that identifies the problem type. Consumers MUST use the "type" string as the primary identifier for the problem type. Relative URIs must be resolved relative to the document’s base URI (= the URI to which the call is made that returned the problem) A problem’s type URI SHOULD resolve to HTML documentation that explains how to resolve the problem.
3b. Relative URI standard compliance (rfc3986)	Relative URIs have to be resolved from: Base URI embedded in content (e.g. html <base> header or xml:base in XML docs, but undefined in JSON) URI used to retrieve the entity
4. message complexity	Complexity increases when more fields required in Problem JSON response

Prior art

1. Zalando REST guide: relative URLs wrt API base path. Absolute URLs if they are stable.

2. Codecentric Blog : urn:problem-type:<id> or absolute URLs if they are stable.

3. DigiPolis Antwerpen: code property as identifier, type as link to doc

4. Problem RFC 3rd party libraries expect the problem type to be stable and support any type of absolute or relative URI but don’t resolve relative URIs

   • https://github.com/t1/problem-details/tree/2.x (implementation of MicroProfile Problem Details proposal)

   • https://github.com/zalando/problem

Current REST guide

• standardized REST problems defined on absolute URIs https://www.gcloud.belgium.be/rest/problems/<id&gt;

• examples with relative URIs for API-specific problem types of format /problems/{problemId}; should be resolvable. Unclear if this is relative URI to API base path.

• rule that links should always be absolute

Current Problem JSON Schema only allows absolute URIs (format: uri); though some OpenAPI tooling doesn’t validate this strictly. format: uri-reference would both allow relative and absolute URIs

Options

Option	Example	description
1) code field	{ "type": "https://b2b-acpt.ksz-bcss.fgov.be /socialStatus/v1/refData/problems/ssinReplaced", "code": "ssinReplaced" }	use "type" only for documentation and new "code" property as identifier (~ DigiPolis Antwerpen)
2) absolute URNs	{ "type": "urn:problem-type:ssinReplaced", "typeHref": "https://b2b-acpt.ksz-bcss.fgov.be /socialStatus/v1/refData/problems/ssinReplaced" }	(~ Codecentric blog) use absolute URNs instead of HTTP URLs as "type" URI, forbid use of relative URIs optionally add another "typeHref" field with a link to the human-readable description; or let client compose doc URL themself
3) type as string	{ "type": "/refData/problems/ssinReplaced", }	when using "type" as identifier, use them as string as-is and don’t resolve relative URIs when using "type" to resolve problem documentation, resolve them as relative URIs 3a) relative link wrt API base path ~ Zalando REST guide. 3b) relative link includes API base path (without domain name)
4) absolute URLs only (env-dependent)	"type": "https://b2b-acpt.ksz-bcss.fgov.be /socialStatus/v1/refData/problems/ssinReplaced"	Clients should parse the type value and use the last part to use as identifier

Evaluation

Option	stable identifier	retrieve doc	Problem RFC standard	relative URI standard	message complexity
1 code field	+	+	—	+	-
2 URN	+	+ (typeHref)	+	+	-
3a string ID w/o base URI	+	+	-	-	+
3b string ID with base URI	- (*)	- (*)	-	+	+
4 absolute URL	- -	+	+	+	+

(*) dependency on technical part in URL, that may change by reverse proxies or tech changes

Impact when requirement not satisfied:

• stable identifier: high

• retrieve doc: medium (low?)

• Problem RFC standard:

  • resolve relative URIs before using them as identifiers: low - everything continues to work when not resolving relative URIs when using them as identifier

  • using another field then type as identifier: high

• relative URI standard: low - API clients and servers often construct the paths based on API’s base URI

• message complexity: medium

Chosen solution

Option 2 was chosen during meeting 29/3.

An additional requirement was raised: low risk on faulty implementation. This exists when resolving relative URIs (both in 3a and 3b). This is the reason why relative URIs are discouraged in the REST guide in the first place.

Note that we explicitly have chosen not follow this recommendation in Problem RFC: "A problem’s type URI SHOULD resolve to HTML documentation that explains how to resolve the problem." This in order to be able to represent API-specific problem types.

The option 2 will be applied to all problem types, even the ones standardized in G-Cloud, to avoid any confusion.

Examples:

{
  "type": "urn:problem-type:cbss:socialStatus:searchCriteriaTooWide",
  "href": "https://api.ksz-bcss.fgov.be/socialStatus/v2/refData/problems/urn:problem-type:cbss:socialStatus:searchCriteriaTooWide",
  "status": 400,
  "title": "Search criteria should be more specific"
}

{
   "type": "urn:problem-type:belgif:payloadTooLarge",
   "instance": "urn:uuid:abcdefghij-1234-1234-adfkjddd",
   "href": "https://www.gcloud.belgium.be/rest/refData/problemTypes/urn:problem-type:belgif:payloadTooLarge", #location might change in the future
   "status": 413,
   "title": "Payload Too Large",
   "detail": "Request message must not be larger than 10 MB",
   "limit": 10485760
}

Recommended structure:

• urn:problem-type:<org>:<api>:<type> OR urn:problem-type:<org>:<type>

  • prefix urn:problem-type because already used by others in practice

  • <org> short identifier for organization (no reverse FQDN because often too long)

  • <api> MAY be used for API-local problem types

  • <type> lowerCamelCase string identifying the type

    • reason lowerCamelCase instead of hyphen-case: URIs more commonly hyphen, but API and other REST guidelines use lowerCamelCase

• optional href linking to problem description HTML

  • href instead of typeHref because shorter, and low risk on confusion with HTML for specific problem instance

  • in link, use full problem URN as the resource id

• instance should be URI (conform to spec; most of the time urn:uuid:<uuid>)