API Reference

Version Management

Smile API Version Management Guide

Introduction

Welcome to the Smile API Version Management guide. This document outlines the versioning strategy and lifecycle policies for the Smile API, helping developers integrate smoothly with our platform while adapting to changes effectively.

Semantic Versioning and Release Phases

The Smile API uses a semantic versioning pattern focused on the major version number, combined with distinct release phases. Each API version may go through up to three phases:

  • Alpha
  • Beta
  • General Availability (GA)

Version Numbering Format

The API version is specified using only the major version number, following this URL pattern:

/v{major}/{phase}
  • For Alpha and Beta phases, include the {phase} in the URL.
  • For the General Availability phase, the {phase} segment is omitted.

Examples:

  • Alpha version: /v1/alpha
  • Beta version: /v1/beta
  • General Availability version: /v1

Version Lifecycle and Evolution

Phases Overview

Alpha Phase (Optional)

  • Purpose: Invite-only testing with selected customers.
  • Access: Not publicly available.
  • Usage: Gathering feedback on new features.

Beta Phase (Optional)

  • Purpose: Early access for all customers after Alpha validation.
  • Access: Publicly available to all developers.
  • Usage: Refining features with broader feedback.

General Availability Phase

  • Purpose: Official, stable release for production use.
  • Access: Publicly available and recommended for all integrations.
  • Usage: Reliable operation with backward compatibility within the major version.

Transition Between Phases

  • Alpha to Beta: May involve breaking changes based on feedback.
  • Beta to General Availability: May involve breaking changes; aiming for stability.
  • Skipping Phases: Some API versions may go directly to Beta or General Availability, omitting earlier phases.

Note: Breaking changes are expected during transitions between phases.

Breaking and Non-Breaking Changes

To maintain stability, Smile API differentiates between breaking and non-breaking (additive) changes.

Breaking Changes

Breaking changes can disrupt existing integrations. These changes will be introduced only in a new major API version.

Examples of Breaking Changes:

  • Removing an entire operation (endpoint).
  • Removing or renaming a parameter.
  • Removing or renaming a response field.
  • Adding a new required parameter.
  • Making a previously optional parameter required.
  • Changing the type of a parameter or response field.
  • Removing enum values.
  • Adding a new validation rule to an existing parameter.
  • Changing authentication or authorization requirements.

Non-Breaking (Additive) Changes

Non-breaking changes enhance the API without affecting existing integrations. These changes will be available in all supported API versions within the same major version.

Examples of Non-Breaking Changes:

  • Adding a new operation (endpoint).
  • Adding a new optional parameter.
  • Adding an optional request header.
  • Adding a response field.
  • Adding a response header.
  • Adding enum values.

API Version Support Policy

To provide ample time for migration and development, the Smile API supports each version according to the following timelines:

PhaseSupport DurationRecommendation
AlphaSupported for 6 months after Beta releaseNot for production use; intended for testing and feedback
BetaSupported for 12 months after General Availability releaseSuitable for early adopters; migration to GA is encouraged
General AvailabilitySupported for 24 months after the next GA API version is releasedRecommended for all production integrations

Example Timeline:

  • v1 Alpha: Released January 2022
  • v1 Beta: Released April 2022
    • v1 Alpha support ends October 2022
  • v1 General Availability: Released July 2022
    • v1 Beta support ends July 2023
  • v2 General Availability: Released January 2024
    • v1 General Availability support ends January 2026

Specifying the API Version in Requests

Include the API version in your API requests using the major version number and, if applicable, the phase.

URL Format:

https://open.smileapi.io/v{major}/{phase}/...
  • For General Availability versions, omit the {phase}.

Examples:

  • Alpha Version (v1):

    https://open.smileapi.io/v1/alpha/resource

  • Beta Version (v1):

    https://open.smileapi.io/v1/beta/resource

  • General Availability Version (v1):

    https://open.smileapi.io/v1/resource

Migration Guidelines

To ensure seamless integration with the Smile API, follow these guidelines when migrating between API versions:

Before Migration

  • Review Documentation: Read the release notes and updated API documentation.
  • Identify Breaking Changes: Pay attention to any listed breaking changes in the new version.
  • Plan Updates: Allocate resources to update and test your integration.

During Migration

  • Use Beta Versions for Testing: Utilize the Beta phase to test your integration and provide feedback.
  • Implement Incrementally: Gradually update your codebase, starting with non-critical components.
  • Maintain Backward Compatibility: If possible, support both the old and new API versions during the transition.

After Migration

  • Monitor Performance: Keep an eye on logs and analytics to catch any issues early.
  • Provide Feedback: Share your experiences with the Smile API team to help improve future versions.
  • Deprecate Old Integrations: Once confident, remove support for the deprecated API versions.