API lifecycle

  • Published on Dec 11, 2025
  • 1 minute(s) read
Prev Next

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:

Example: API response header for deprecated endpoint

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.