--- title: "API and Architecture" url: https://develop.sentry.dev/sdk/getting-started/standards/api-architecture/ --- # API and Architecture This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. Statusstable Version`1.0.0`[(changelog)](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#changelog) These standards guide how SDKs are designed and evolved. The core philosophy: prefer server-side logic, protect public API stability, and give users smooth upgrade paths. SDKs often stay installed for years after release, so decisions made today have long-lasting consequences. ## [Server-side (Relay) vs. SDK implementation](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#server-side-relay-vs-sdk-implementation) Stablespecified since 1.0.0 When deciding where new logic should live, default to server-side (Relay). Processing data in Relay keeps behavior consistent across SDK versions and avoids duplicating logic in clients that may remain deployed indefinitely. Put logic in the SDK only when it genuinely needs to run client-side: * It **MUST** run before data leaves the customer's application (e.g., user-controlled filtering like `before_send_*`) * It requires access to platform-specific APIs * It's strictly latency-sensitive * It **MUST** function in offline scenarios If data has already been collected, transform it in Relay. *** ## [Forward compatibility](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#forward-compatibility) Stablespecified since 1.0.0 SDKs typically outlive individual API versions. A user might stay on an SDK release for months or years, while server responses continue to evolve. SDKs **MUST** handle this gracefully: * Ignore unknown fields, categories, or dimensions rather than erroring * Tolerate missing optional fields * Accept new enum values without crashing * Handle rate limiting responses The general principle: additive server-side changes **MUST NOT** break existing SDK versions. *** ## [Public API changes](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#public-api-changes) Stablespecified since 1.0.0 Any change to public API — adding, modifying, deprecating, or removing — **REQUIRES** approval from an [SDK Senior Engineer](https://github.com/orgs/getsentry/teams/sdk-seniors). Public API includes anything a user can call, import, configure, subclass, or otherwise reference. When in doubt, check for usage in public repositories. If you're still unsure, treat it as public. How each SDK detects API changes (CI snapshot diffs, etc.) varies by language, but the approval requirement applies everywhere. *** ## [Semantic conventions](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#semantic-conventions) Stablespecified since 1.0.0 Semantic conventions are shared across SDKs, ingest, and the product — treat them like public API. New attributes **MUST** be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions) before SDK implementation. The process: 1. Open a PR to sentry-conventions 2. Get code owner approval 3. Wait at least 3 business days 4. Implement in the SDK This ensures attributes are reviewed and consistent across the ecosystem before any SDK ships them. Changes to existing attributes (renaming, removing, or changing semantics) are breaking changes and **MUST** follow the [breaking change process](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-and-deprecation). The sentry-conventions repo has its own deprecation lifecycle — deprecated attributes go through a `backfill` period (at least 90 days) before moving to `normalize`, and replacements and aliases **MUST** be maintained for both old and new names during the transition. *** ## [Breaking changes and deprecations](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-changes-and-deprecations) Stablespecified since 1.0.0 Breaking changes and deprecations are closely linked — every breaking change goes through a deprecation period first. Both follow a lifecycle designed to give users time and guidance to migrate. ### [Deprecation lifecycle](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#deprecation-lifecycle) Deprecations of public APIs, integrations, and supported platforms follow three stages: 1. **Announce** in a minor release: add a runtime warning (where possible), update the changelog and docs, and publish a migration guide. Warnings **MUST** include the replacement, a code example, and a link to migration docs. 2. **Keep it working** for at least one subsequent minor release (e.g., deprecated in X.Y, still functional in X.(Y+1)). 3. **Remove** only in the next major release (X+1.0). Deprecating an entire SDK follows a separate, more involved process — see the [Deprecating an SDK](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk.md) playbook. ### [Breaking changes](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-changes) Breaking changes **MUST** follow the [breaking changes playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes.md). They can only ship in major versions; opt-in previews are allowed in minor versions. Every breaking change **MUST** include: * A migration guide with copy-pastable examples * A changelog entry using the `BREAKING CHANGE:` notation * Validation of the migration guide using an LLM to ensure clarity and completeness Deprecation timelines can vary by SDK, but the stages and process apply everywhere. *** ## [Changelog](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#changelog) | Version | Date | Summary | | ------- | ---------- | ------------------------------------- | | `1.0.0` | 2026-02-18 | Initial API and Architecture standard |