All Versions

Version 1
Version 2


Page tree

Supplier API v2

Skip to end of metadata
Go to start of metadata

Table of Contents

Overview

We are committed to providing you with a stable and consistent API. We know how frustrating it can be when a new version of an API forces you to rewrite all of your implementation code just to get access to a few new features. We hope that our versioning method will help to eliminate those types of issues.

The following sections on this page will explain our versioning process.

API Versions

The API Version is specified as part of the URL for the API endpoints. A new API Version indicates far reaching changes in the API's low level functionality. As a consumer of the API, it may require extensive code changes on your behalf to migrate to a new API version. We want to avoid this imposition as much as possible.

Supplier API v1 did not provide a foundation that could grow and evolve easily without breaking existing implementations. So, we created Supplier API v2 to address this need. We believe that the standards implemented by v2 will preclude the need for any additional API versions. 

Versioned Resources

The key to the flexibility provided by Supplier API v2 is the use of Versioned Resources. As developers, we can evolve a single resource without the need to create an entirely new version of the API. We can easily support multiple versions of individual resources indefinitely. As consumers of the API, you can adopt new versions of individual resources on an as-needed basis without the need to change an entire implementation at one time.

There is no dependency between read versions and write versions. In other words, it is possible for you to write one version of a resource to the API, but request to get a different version back from the API. This extends your ability update to newer resource versions only where necessary.

Version Labels

Our resource version labels use the pattern {major-version}.{minor version}

Minor Versions

A new minor version is created for a resource when we believe that the change will be non-breaking. In most cases, you should be able to consume a new minor version of a resource with no code changes required. This includes things like adding a new field to an existing data model. 

Major Versions

Major versions are create when we consider the change to be breaking. A code change will likely be required to consume a new major version of a resource. These changes include things like removing or renaming a field, or changing a field's data type.

Resource Versioning Example

To illustrate how we version our resources, consider an imaginary resource model for a pet. The pet model is originally defined as version 1.0.

NameTypeDescription
typestringThe type of pet
namestringThe pet's name
ageintegerThe pet's age in years

 

Later, we decide to add the birth date and gender of the pets. The addition of the new fields should be compatible with the original model, so we will create a new minor version 1.1.

NameTypeDescription
typestringThe type of pet
namestringThe pet's name
ageintegerThe pet's age in years
birthDatedateDate the pet was born
genderenumerationGender of pet; "Male", "Female"

 

Storing both the age and birth date for each pet is redundant. We decide to remove age since we can calculate age from birth date. Removing a field will cause us to assign a new major version, 2.0.

NameTypeDescription
typestringThe type of pet
namestringThe pet's name
birthDatedateDate the pet was born
genderenumerationGender of pet; "Male", "Female"

 

Finally, we evolve and believe we have found a more flexible way to represent the data. The new model is simply an array of named values. So, we completely change the model, again creating a new major version 3.0

NameTypeDescription
attributeNameenumerationThe name of the attribute. One of "Type", "Age", "Gender"
attributeValuestringThe value of the attribute.

Specifying the Version for Response Data

To specify the version of the resource that you would like to receive in the API response, you will use the custom HTTP headers Accept-Version. Depending on how flexible your code is, you can specify the version in any one of the following ways:

  1. Do not send the Accept-Version header. This is the equivalent of sending "Accept-Version": "1.0"
  2. Send the full version number in the Accept-Version header, such as "Accept-Version": "1.1"
  3. Send just the major version followed by .x to indicate that any minor version is acceptable. In this case the API will return the latest minor version for the major version requested. For example, "Accept-Version": "2.x"
  4. Send "Accept-Version": "latest" which will always return the latest version of the resource model. Use this with caution, as the change illustrated above between version 2.0 and 3.0 would most likely cause problems in any implementation.

The response will always contain a Content-Version header with the full version number of the resource being returned.

Related Errors

HTTP StatusError CodeDescription
406: Not Acceptableversion-not-acceptable The Accept-Version header does not specify a valid version for the requested resource

Example: Proper use of the Accept-Version Header

The following example request is setting the Accept-Version header to 1.x, which is requesting the latest minor version for version 1 of the members resource.

The Content-Version header in the response indicates that the API has returned the version 1.0 representation of the members resource.


GET /api/v2/members/M0001
Accept: application/json
Accept-Version: 1.x
Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0

HTTP/1.1 200
Content-Type: application/json; charset=utf-8
Content-Version: 1.0
{
  "memberId": "M0001", 
  "language": "EN", 
  "email": "m0001@example.com",
  "firstName": "John",
  "lastName": "Snow",
  "birthDate": "1984/01/20",
  "address": { 
    "country": "US",
    "streetAddress": null,
    "postalcode": "10101"
  } 
}

Example: Invalid Version Specified in the Accept-Version Header

This example sends the Accept-Version header using an invalid version number, 0.5.

An appropriate error response is returned.

GET /api/v2/members/M0001
Accept: application/json
Accept-Version: 0.5
Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0

HTTP/1.1 406
Content-Type: application/json; charset=utf-8
{
  "errorCode": "version-not-acceptable",
  "errorMessage": "Version 0.5 is not defined for this resource",
  "errors": []
}


Specifying the Version for Request Data

When making a request in which you are sending data to the API, you must include the full version of the resource model being sent using the Content-Version header. If the header is missing then the API will assume that the request body is using version 1.0 of the resource model.

Wildcards such as 1.x or latest are not allowed in the Content-Version header. You must specify the full version number!

Related Errors

HTTP StatusError CodeDescription
415: Unsupported Media Type

invalid-content-version

An invalid version number was specified in the Content-Version header.
422: Unprocessable Entityinvalid-contentThe request body was successfully decoded, but could not be understood based on the Content-Version that was specified.
If Content-Version was not specified, 1.0 is assumed.
Additional details can be found in the errors object of the response.

Example: Proper Use of the Content-Version Header

This example shows a properly formatted Content-Version header with a valid 1.0 version of the members resource being submitted.

POST /api/v2/members
Content-Type: application/json
Content-Version: 1.0
Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0
{
  "memberId": "M0001", 
  "language": "EN", 
  "email": "m0001@example.com",
  "firstName": "John",
  "lastName": "Snow",
  "birthDate": "1984/01/20",
  "address": { 
    "country": "US",
    "streetAddress": null,
    "postalcode": "10101"
  } 
}

HTTP/1.1 201


Example: Invalid Version Specified in the Content-Version Header

This example illustrates sending an invalid version number, 1.x, in the Content-Version header.

An appropriate error response is returned.

POST /api/v2/members
Content-Type: application/json
Content-Version: 1.x
Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0
{
  "memberId": "M0001", 
  "language": "EN", 
  "address": { 
    "country": "US"
  } 
}

HTTP/1.1 415
Content-Type: application/json; charset=utf-8
{ 
  "errorCode":"invalid-content-version",
  "errorMessage":"Request body is invalid as described by version 1.0 of this resource.",
  "errors": []
}

Example: Data Model Used in the Request Data Does Not Match The Version of the Resource Specified in the Content-Version Header

The next example illustrates a request where the request body includes a data element which is not defined for the resource based on the version specified in the Content-Version header.

An appropriate error response is returned, including an errors object with additional details about the cause of the error.

POST /api/v2/members
Content-Type: application/json
Content-Version: 1.0
Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0
{
  "memberId": "M0001", 
  "language": "EN", 
  "email": "m0001@example.com",
  "firstName": "John",
  "lastName": "Snow",
  "birthDate": "1984/01/20",
  "anniversary": "2018/02/14",
  "address": { 
    "country": "US",
    "streetAddress": null,
    "postalcode": "10101"
  } 
}

HTTP/1.1 422
Content-Type: application/json; charset=utf-8
{
  "errorCode":"invalid-content",
  "errorMessage":"Request body is invalid as described by version 1.0 of this resource.",
  "errors": [
    {
      "href":"http://local-supplier.cmix.com/api/v2/members",
      "class":"members",
      "identifier":null,
      "failedValidations": [
        {
          "error":"invalid-data-element",
          "path":"/anniversary",
          "value":"2015/02/14"
        }
      ]
    }
  ]
}

  • No labels
Write a comment…