Wrapping HTTP status codes when schema stitching

[Dzeri96]

I've recently started building a GraphQL gateway for our microservice architecture and came across an interesting case when using GraphQL over HTTP: wrapping the status codes.

According to the WIP spec for GQL over HTTP, the code should be set accordingly, however this presents an interesting challenge in the context of schema stitching.
I know that the purpose of this tool is stitching on a level above the transport, but handling external endpoints (that follow this spec) is perfectly realistic in my opinion.
The purpose of this issue is to start a discussion and gain insight, so I'm just going to list out some implementation problems and solutions I've identified:

The first one is exposing HTTP transport details via an executor.
As it currently returns an ExecutionResult, these details could possibly go into the extensions property.
These would then get picked up by the server, like apollo, and applied to the appropriate transport fields.
I'd like to know if there is a more elegant solution for this.

The second issue is differentiating gateway-breaking errors from user-facing ones.
For example, in the schema introspection step, a 401 would mean that the service itself is not authenticated, and not the user.
These cases should obviously be handled differently, and my solution would be to create two different executors, but I'm sure there are many edge cases, like stuff breaking during runtime.

In any case, I'd like to hear some opinions on the matter.

[n1ru4l]

Hey @Dzeri96, a common practise for error (HTTP) codes that happen during execution is to attach them to the GraphQLErrors instances as extension fields, and then loop through them before sending the execution result to the client in order to determine and set the correct status code.

The hardest thing here would be to decide which status code wins in case there are multiple errors with a status code extension.

I am not the biggest fan of this approach and I think granular HTTP status codes make more sense when implementing a strict REST API (where each route describes a single entity), compared to a GraphQL HTTP API (where the single route could yield any amount of interconnecting entities).

A pattern a few APIs use is the usage of union and interface (or @oneOf) types for modelling such errors within your GraphQL schema instead of relying on status codes instead.

• https://sachee.medium.com/200-ok-error-handling-in-graphql-7ec869aec9bc
• https://blog.logrocket.com/handling-graphql-errors-like-a-champ-with-unions-and-interfaces/
• https://www.the-guild.dev/blog/graphql-error-handling-with-fp

[n1ru4l]

Answering part two of your discussion in a seperate branch so each discussion branch can be more focused.

If you want to differenciate gateway breaking errors (I assume introspection errors?) from normal errors you could identify such errors by checking whether the executed operation is an introspection operation (and selects the schema coordinate Query.__schema).

We actually built GraphQL Hive as a schema registry in order to push schema validation and integrity checking to build/deploy time instead of doing it after the deployment (during runtime). Maybe this is something you might be interested in.
Again for user-facing errors I prefer to model these kind of errors as part of the GraphQL schema instead of throwing them within the resolvers.
Alternatively, a error masking approach could help you differenciate user-facing errors from unexpected (gateway) errors e.g. via a specific extensions field on the errors.