Add versioning to the error response

[mkokotovich]

The CAF team has started to think about implementing the new error response formats in UIs.

One thing that we discussed that could help this transition (and future transitions!) is adding a version string to the error response. Something like:

"spsApiStandardVersion": "1"

(or whatever, just some sort of a version).

Then the client of the API can look for that string and know what shape to expect for the response body. If that key isn't there, it knows it is a legacy response. And when we switch to a latest and greatest error response in 5 years, we can bump the version string for easier migrations.

That way UIs that are calling multiple APIs or APIs with a mixture of old and new responses will be able to automatically parse the different error types.

[shifr]

I would think about errors and all the shared domain models/responses that follow the current standard and could morph with time.

[travisgosselin]

Connecting versioning to domain models is a slightly different use-case I think, agreed it is something we need to figure out... today those are versioned in SwaggerHub models. Definitely more discussion on the evolution of domain versions is needed... but I think that is more interesting in all other domains except errors, given the RFC7807 takes that into consideration already.

[travisgosselin]

This is a great callout about dealing with multiple versions of the schema.

An exciting aspect of the error format is that it follows not just SPS standards but a broader community movement around RFC7807 (https://docs.platform.spscommerce.com/api-design/standards/errors/#problem-details). Upfront this RFC defines the response content-type to differentiate the payload: Content-Type: application/problem+json from other pre-standard versions at SPS. This is also essential for consuming applications to distinguish deserialization of the 2xx payload from the error content.

The Problem Details format is also intended to be pretty durable given its flexibility. Of course thats only referring to a few top level fields, offering complete extensibility inside that you might modify and add other schema. For those customizations the approach would be to add a "type" definition that is unique in defining a more specific schema for additional fields. For example you might use type: https://example.net/validation-error to define custom invalid-params extensions. You might also use type: https://example.com/probs/out-of-credit to add balance and account information about the credit issue.

SPS Commerce has not defined its standard types yet, and we have tried to defer this with a single representation of our ProblemDetails model with a "context" key for now. Type would come in as we mature more and define standardized schemas for different platform level error types. We could have added in a single new type to represent our current standard, but that work has not been done yet, but should not be a breaking change to add in the future (there is also a growing community standard that is talking about a centralize database of registering the types that I am interested to see how it plays out.

If in general we move away from ProblemDetails in the future for whatever reason that would of course indicate a change to Content-Type and the error schema. Additionally, if there is a scenario that requires us to evolve the base fields used in ProblemDetails a versioning of the content-type would work there to:

Content-Type: application/problem+json; version=2.0

At this point in time, I'm not keen on necessarily connecting our coupling API Standard Version numbers to schemas as I'm not clear on the precedence that sets for versioning general (over using conten-type practices). We are also still verifying the approach to standards versioning itself.