Skip to content

Upgrading the SDK

Treat both SDK changes and OpenAPI changes as integration-contract changes.

The repository pins the source contract at resources/openapi.yaml. EndpointCoverageTests ensures that every HTTP method/path pair in that file has an entry in EndpointCatalog and that the catalog does not contain extra operations.

When the server contract changes:

  1. Replace the pinned OpenAPI file with the reviewed version.
  2. Run the coverage test to identify new or removed operations.
  3. Update request DTOs and response models.
  4. Add new enum values cautiously. Unknown enum values can break strict enum deserialization and should be treated as a compatibility decision.
  5. Update service methods and endpoint scopes.
  6. Add tests for new request/response behavior.
  7. Regenerate the contract reference documentation.
  8. Run integration tests against a compatible deployment.

The SDK preserves unknown object properties through JsonExtensionData, but enum additions still require care because enums are intentionally strongly typed.