API Guidelines
  • adidas API Guidelines
  • General Guidelines
    • Introduction
    • API First
    • Contract
    • Immutability
    • Robustness
    • Common Data Types
    • Version Control System
    • Minimal API Surface
    • Rules for Extending
    • JSON
    • Security
    • Tooling
  • REST API Guidelines
    • Introduction
    • Core REST Principles
      • OpenAPI Specification
      • API Design Platform
      • Design Maturity
      • Testing
    • Protocol
      • HTTP
      • TLS
      • Separate Concerns
      • Request Methods
      • Status Codes
    • Message
      • Message Formats
      • Content Negotiation
      • HAL
      • Problem Detail
      • Foreign Key Relations
    • Application
      • Corporate Data Model
      • Common Data Types
    • Execution
      • Pagination
      • Long Running Tasks
        • Polling
        • Callback
        • Files Upload
      • Batch Operations
      • Search Requests
      • Query Requests with Large Inputs
      • Choosing Fields and Embedded Resources
      • Localization
      • Rate Limiting
      • Caching
      • Testing Enviroments
    • Evolution
      • Naming Conventions
      • Reserved Identifiers
      • URI Structure
      • Changes and Versioning
      • Phasing out Old Versions
    • Guides
      • API Testing CI Environment
      • Complete API Development
    • API Clients
      • Loose Coupling
    • Further References
  • Asynchronous API Guidelines
    • Introduction
    • Core Asynchronous Principles
      • Event Driven Architectures
      • Messages
        • Commands
        • Queries
        • Events
          • Events as Notifications
          • Events to Replicate Data
      • Protocols
      • Coupling
      • Bounded Context
      • Stream Processing
      • Naming Conventions
      • Tooling
        • Editors
        • Command Line Interface (CLI)
        • Generators
    • Kafka Asynchronous Guidelines
      • Introduction
        • Why AsyncAPI?
      • AsyncAPI Version
      • Internal vs Public Specifications
      • Key/Value Format
      • Message Headers
      • Specification Granularity
      • Self-Contained Specifications
        • Meaningful Descriptions
      • Schema Data Evolution
        • Backward Compatibility
        • Forward Compatibility
        • Full Compatibility
      • Automatic Schema Registration
      • Contact Information
      • AsyncAPI ID
      • Servers
      • Channels
      • Schemas
      • Security Schemes
      • External Docs
Powered by GitBook
On this page
  • Identifier Stability (No URI Versioning)
  • Backward-incompatible Changes
  • Representation Format Changes
  • API Description Versioning
  1. REST API Guidelines
  2. Evolution

Changes and Versioning

PreviousURI StructureNextPhasing out Old Versions

Last updated 5 years ago

The fundamental principle is that you can’t break existing clients, because you don’t know what they implement, and you don’t control them. In doing so, you need to turn a backwards-incompatible change into a compatible one.

–

Any change to an API MUST NOT break existing clients.

Any change to: 1. Resource identifier (resource name / URI) including any query parameters and their semantics 2. Resource metadata (e.g. HTTP headers) 3. Action the resource affords (e.g. available HTTP Methods) 4. Relation with other resources (e.g Links) 5. Representation format (e.g. HTTP request and response bodies)

MUST follow the .

Identifier Stability (No URI Versioning)

A change MUST NOT affect existing resource identifiers (name / URI). Furthermore, a resource identifier MUST NOT contain a semantic version to convey a version of resource or its representation format.

The reason to make a real REST API is to get evolvability … a "v1" is a .... to your API customers, indicating RPC/HTTP (not REST)

–

Example

Adding a new action to existing resource with identifier /greeting doesn't change its identifier to /v2/greeting (or /greeting-with-new-action etc.).

Backward-incompatible Changes

A change to resource identifier, resource metadata, resource actions and resource relations that can't follow the MUST result into a new resource variant. Existing resource variant MUST be preserved.

A change to representation format SHOULD NOT result into a new resource variant.

Example

Currently, optional URI Query Parameter first on an existing resource /greeting?first=John&last=Appleseed needs to be made required. Since this change violates the 3rd rule of extending and could break existing clients a new variant of the resource is created with different URI /named-greeting?first=John&last=Appleseed.

Representation Format Changes

A representation format is the serialization format (media type) used in request and response bodies, and typically it represents a resource or its part, possibly with additional hypermedia controls.

Example

Media type before a breaking change:

application/vnd.example.resource+json; version=2

Media type after a breaking change:

application/vnd.example.resource+json; version=3

NOTE: In the case of technical limitations with semi-colon separated HTTP header values, the semantic version MAY be incorporated in the media type identifier, for example: application/vnd.example.resource.v2+json However, the use of semicolon-separated version information is preferred.

API Description Versioning

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards-compatible manner

  • PATCH version when you make backwards-compatible bug fixes

The API Description version SHOULD be updated accordingly to API design change.

Example

Following API Description

swagger: '2.0'
info:
  version: '2.1.3'
  title: '[Demo] Inventory API'
  description: 'Inventory service API'

Has MAJOR version 2, MINOR version 1 and PATCH version 3.

Recommended Reading

If a change can't follow the Rules for Extending the representation format media type MUST be changed. If the media type has been changed the previous media type, MUST be available via .

If the media type conveys the version parameter, the version parameter SHOULD follow .

API Description in the OpenAPI specification format MUST have the version field. The version field MUST follow :

Mark Nottingham
Rules for Extending
Roy T. Fielding
Rules for Extending
Content Negotiation
Semantic versioning
Semantic versioning
Evolving HTTP APIs