API conventions (GraphQL)

The rule

Connections sit on top of the shared offset paging. PageExtensions in GraphQL/Extensions/ makes each cursor a base64 offset:<n> and turns an after cursor back into an offset. A cursor that didn't come from us is a validation error.

Mutations report the failures a caller can fix as typed errors in the payload, through [Error<T>] on the mutation. Each error type in GraphQL/Errors/ takes the Application exception in its constructor and implements the Error interface, so it has a message:

Queries, and anything a mutation doesn't declare, go through ApplicationErrorFilter in GraphQL/Errors/, which maps Application exceptions onto GraphQL errors:

Hot Chocolate returns an unexpected exception to the client and logs nothing, so the filter logs it as Error, with the exception and the field path (serilog). The filter is built from the schema's services, so ProgramExtensions hands it a logger from the application's with GetRootServiceProvider().

Steps

1. Name new fields and arguments after the data, not the Application class (reviews, not getReviewsQuery).
2. Decide nullability on purpose: non-null for fields that always have a value, nullable for a field whose resolver can throw.
3. Return a connection for any list that can grow. Never an unbounded list.
4. Report a new kind of failure as an Application exception. Add an error type for it in GraphQL/Errors/ and an [Error<T>] on each mutation that can raise it, and a case to ApplicationErrorFilter with its own code for queries, with a unit test in tests/Presentation.Tests.Unit/GraphQL/Errors/.
5. Test each error code or error type in the field's integration tests (test-design). Ask for errors with errors{__typename,...on Error{message}}.

Example

// src/Presentation/GraphQL/Errors/ApplicationErrorFilter.cs
NotFoundException notFoundException => ErrorBuilder.FromError(error)
    .SetMessage(notFoundException.Message)
    .SetCode("NOT_FOUND")
    .Build(),

Don't

• Expose offset arguments or backward paging.
• Change a field's name, type or nullability without updating the schema snapshot and saying so in the pull request. It breaks clients.
• Put stack traces or internal detail in an error message or extension.
• Add a second error filter.

Check

dotnet test tests/Presentation.Tests.Integration