Best practices for errors

[connorjs]

Starting a thread to discuss best practices for modeling errors in TypeSpec. While the crux of the discussion falls more to the type of API being modeled (let’s call it REST/RESTful/RPC-as-REST), I think SDLs like TypeSpec influence API authors regardless.

So, what are your best practices for errors?

I’ll seed the discussion with some thoughts.

1. TypeSpec has the @error decorator, which likely gets coupled with a 4xx or 5xx @statusCode.

2. How does TypeSpec client generation work regarding error modeling? Is this a TypeSpec thing or an Open API thing (assuming HTTP as the protocol).

3. Smithy’s @error trait has explicit differentiation between "client" and "server". I believe this assists code generation, mainly on the AWS side where the AWS Java SDKs have exception hierarchies. See Exception handling for the AWS SDK for Java 2.x

4. I recently came across RFC 7807, which introduces a scheme for “problem details“ objects.

5. What belongs in “core” TypeSpec (cross protocol) vs. HTTP or Open API?

6. Does Microsoft have its own API modeling best practices (that are open sourced). If so, can (should?) TypeSpec push API authors to those best practices?

Again, just opening a discussion in hopes to hear some thoughts from the community.

Opened as Q&A to allow selecting an "answer" if someone gives great resources and recommendations. Otherwise, this mostly represents a "General" discussion.

[connorjs]

List of other resources I have found after original post.

• (2023-11-06) Microsoft REST Guidelines

[markcowl]

The intention is that @error represents a protocol-independent error. In Http, this could be coupled with 4xx and 5xx status code ranges, but it is more common in OpenAPI the use a single schema to represent both (the default response).

TypeSpec client generation generally regards the error model as data that is returned using the language specific mechanism (for example, exceptions). In TypeSpec client generation, there is generally a default language-specific representation of errors, with extra client-specific decoration to override the defaults (not currently public)

We have a work item to add a representation for RFC 7807 problem details

The intention is, indeed that core typespec contains protocol-independent error modeling, with the protocol libraries containing protocol-specific representations