## API Versioning Policy

### How Versioning Works

- RUCKUS One uses **content negotiation** for versioning.
- By default, responses use `application/json` and always return the **latest version** of the resource.
- To lock to a specific version, set the `Accept` header to:

```
application/vnd.ruckus.v<version>+json
```
- **We always support the root version (v1, v2, etc.) for all APIs.**
  - For example, if an API has versions `v1` and `v1.1`, both are available, but `v1` will **always remain supported** as the root version.
  - This ensures customers who prioritize **consistency and stability** over new features can lock to the root version and avoid the risk of API changes.
- Each endpoint has its **own versioning**—there is no global API version.


### When Do We Create a New Version?

- **Only for breaking changes**, such as:
  - Removing or renaming fields
  - Changing data types
  - Making optional fields required
- **Non-breaking changes** (e.g., adding optional fields or expanding enums) do **not** require a new version.
- Major structural changes may require a new endpoint path, but **we do not use URI versioning** (e.g., `/v1/`).


### Deprecation & Lifecycle

- When a breaking change is released, the old version is **deprecated immediately**.
- Deprecated versions remain supported for **at least 6 months**.
- Removal happens only during the **annual removal window in March**, giving customers a predictable migration timeline.


### Customer Notifications

- Notifications are sent via **email or SMS** to subscribers.
- All upcoming changes are listed in the **"Upcoming Changes"** section of the API docs.
- Deprecated endpoints include headers:
  - `Ruckus-Deprecated` → Indicates deprecation
  - `Ruckus-Current-Version` → Shows the latest version