Skip to content

API Standard — GraphQL & REST

v1.0 — 2026-06-06

GraphQL server (HotChocolate)

  • Implementation-first (pure C#) — the ExpertGroup pattern: modular [ExtendObjectType] query/mutation classes, [Service] injection, IActorIdentityGuard<T> authorization checks at the top of every resolver.
  • DataLoaders for every nested resolver — N+1 is a review-blocking defect.
  • Middleware order: UsePaging → UseProjection → UseFiltering → UseSorting.
  • Pagination: cursor/Relay Connections for unbounded lists (the existing PagingResult<T>/LimitInput pattern is acceptable for admin grids).
  • Document the schema: [GraphQLDescription] on public types/fields.
  • Enable cost analysis / operation budgets (HC v16) on internet-facing endpoints.

Schema design

  • Fields nullable by default; non-null only when guaranteed (consider error blast radius).
  • Mutations return payload types (not bare entities); consistent verb naming.
  • Never version a GraphQL schema — evolve additively, mark removals @deprecated(reason: "...") first.

REST (where used)

Follow the Azure REST API Guidelines (the old root Guidelines.md is deprecated):

  • Plural-noun kebab-case URLs (/work-orders/{id}), camelCase JSON.
  • Explicit api-version parameter; RFC 7807 problem-details error bodies.
  • PUT/PATCH idempotent; correct status codes (no 200-with-error-body).

All APIs

  • AuthN/AuthZ at the edge (JWT/OIDC via ExpertGroup.Core.Hosting.AspNetCore or Entra ID); authorization re-checked in resolvers/handlers, never trusted from the client.
  • Validate every input; return clear, non-leaking error messages.

Sources: HotChocolate v16 · DataLoaders · GraphQL best practices · Azure REST guidelines