When designing or extending APIs, ensure the request/response schema and behavior strictly preserve invariants and provider compatibility.
Apply these rules:
1) Don’t expose unsafe state transitions
- If a field (e.g., status) must be controlled by an internal state machine, do not add GraphQL mutations/resolvers that allow clients to set it directly—even if the input object contains the field.
2) Use explicit, strongly-typed API models for configuration/mappings
- Prefer dedicated GraphQL types/inputs over generic JSON scalars for mapping objects.
- Validate invariants at the API boundary (e.g., duplicate keys) and ensure the field is reliably returned/persisted (avoid “saving others then dropping mapping” scenarios).
Example (schema shape for typed mappings):
input ReasoningEffortMappingInput {
from: String!
to: String!
}
type ReasoningEffortMapping {
from: String!
to: String!
}
input UpdateChatSettingsInput {
reasoningEffortMapping: [ReasoningEffortMappingInput!]
}
3) Preserve the intended API lifecycle across fallback paths
- If you add auto-aggregation or fallback handling, do not accidentally bypass required middleware phases. Streaming-phase hooks should still execute when the stream is processed.
4) Match third-party spec requirements exactly and guard provider-specific behaviors
- Include fields even when they are zero if the provider spec requires them.
- Apply provider-specific selectors/decorators only when the negotiated API format supports them (use an explicit condition/guard).