Versioning & Deprecation Policy

Semantic versioning principles, URL path stability, template evolution, and sunsetting timelines.

The Open Graph Image Generator API is built with long-term backward compatibility as a core engineering tenet. Social share images embedded in published blog posts, forum entries, and chat archives must continue to render correctly for years without visual degradation or broken links.

API Path Versioning (/v1)

All public endpoints are scoped under major version prefixes:

https://api.generativeog.in/v1/images/minimal.png
https://api.generativeog.in/v1/layouts
https://api.generativeog.in/v1/capabilities

Breaking vs. Non-Breaking Changes

The following changes are considered non-breaking and may occur within the v1 lifecycle:

  • Introducing new optional query parameters.
  • Adding new built-in layouts (e.g. adding a new layout id).
  • Adding new supported font families or expanding Unicode script coverage.
  • Enhancing rendering performance or reducing image file sizes without altering visible layout dimensions.
  • Adding new response headers or non-breaking JSON fields.

The following changes are considered breaking and will never occur under v1:

  • Removing existing query parameters or altering their data types.
  • Changing the default dimensions or aspect ratios of existing layouts.
  • Removing or altering the visual identity of existing layouts without introducing a new version identifier.
  • Removing any existing error codes or changing their semantics.

Layout Versioning

Every layout returned by the /v1/layouts endpoint contains an explicit version property (e.g. version: 1).

If a built-in wireframe layout requires substantial visual restructuring or a redesigned layout hierarchy, rather than altering the appearance of millions of existing published image links:

  1. A new layout version or unique layout ID will be published (e.g., article-v2).
  2. The existing layout ID will remain available and functional indefinitely.

Deprecation Notice Timeline

If an endpoint or major API version must ever be sunset:

  1. Advance Notice: A minimum notice period of 6 months will be announced on the Changelog and documentation portal.
  2. Deprecation Headers: Responses will include the standard HTTP Deprecation and Sunset headers specifying the end-of-life timestamp and migration link.
  3. Fail-Safe Fallbacks: The platform will strive to alias deprecated endpoints to closest compatible layouts rather than returning broken image responses.