Compatible changes
These changes are safe for clients that ignore unknown fields and handle unknown enum values:- Adding endpoints.
- Adding optional request fields.
- Adding response fields.
- Adding enum values.
- Adding error codes.
- Changing response field order.
- Changing opaque token or cursor formats.
Breaking changes
These changes require notice and a migration path:- Removing endpoints.
- Renaming request or response fields.
- Changing field types.
- Making optional request fields required.
- Removing enum values.
- Changing authentication behavior.
- Changing error response structure.
Client guidance
- Ignore unknown response fields.
- Handle unknown enum values.
- Treat IDs, tokens, client secrets, and cursors as opaque.
- Use idempotency keys for retryable mutations.
- Read errors by machine-readable
code, not only by message text.