---
title: "API lifecycle"
slug: "api-lifecycle"
updated: 2025-12-11T14:00:22Z
published: 2025-12-11T14:00:22Z
canonical: "docs.newstore.com/api-lifecycle"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API lifecycle

This page explains how NewStore APIs progress from Beta to General Availability (GA), how we communicate changes, and what to expect for deprecations and sunsets.

## Lifecycle stages

### Beta (Preview/Experimental)

Purpose: early access for evaluation and feedback.

- May change without notice, including breaking changes.
- Clearly labeled in the API explorer.
- Not recommended for production-critical workflows; intended for evaluation purposes only.
- Typical Beta phase duration: 3–6 months.

### General Availability (GA)

Purpose: stable, production-ready APIs.

- Backward compatibility is maintained within the same version; additive, non-breaking changes may occur.
- Breaking changes are introduced only in a new version.
- Fully documented with usage examples.
- Operated with production monitoring and SLAs.

### Deprecation

What “deprecation” means: an API or API version is announced for future removal. It should not be used for newly implemented integrations, and you should migrate existing integrations to the documented alternative.

- Minimum notice before removal (sunset): 12 months.
- Deprecated API endpoints are clearly labeled in docs and API responses.
- We provide a migration path with guides and examples.
- We maintain the same support levels throughout the deprecation period as we do for non-deprecated endpoints.

### Sunsetting (removal)

After the announced date:

- Documentation is updated to reflect removal and to point to supported alternatives.
- Endpoints are disabled and return a ‘HTTP 410 Gone’ error code.

Example timeline from deprecation to sunsetting (illustrative)

- 01.01.2027: Deprecation announcement + Sunset date published
- 01.01.2027 until 01.01.2028 (12 months deprecation period): API remains available
- After 01.01.2028: API is removed

---

## Change communication

We announce changes via:

- Deprecation page: [https://docs.newstore.com/docs/deprecation-notices](https://docs.newstore.com/docs/deprecation-notices)
- API endpoint documentation
- Response headers (see below)
- Direct customer notifications for impactful changes including migration guides

*Example: API response header for deprecated endpoint*

```javascript
GET /endpoint

HTTP 200

Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 UTC
Link: <https://docs.newstore.com/docs/deprecation-notices>; rel="deprecation"; type="text/html"
Link: <https://{tenant}.{stage}.newstore.net/replacement/resource>; rel="alternate";

... original response
```

## Breaking changes

A breaking change is a modification to an API endpoint that may cause existing clients to fail, behave incorrectly, or require code changes to continue functioning. We consider the following to be breaking changes:

- Removing or renaming an API endpoint, resource, or operation
- Changing request or response structure, including:
  - renaming fields
  - removing fields
  - making previously optional fields required
  - altering data types, formats, or value ranges
- Modifying semantics of an existing operation in a way that changes expected outcomes
- Altering authentication or authorization requirements for existing endpoints
- Removing query parameters or changing default values
- Changing error codes or error formats in ways that break existing clients
- Introducing or changing rate limits to be more restrictive than before.