Versioning filter

Purpose

Versioning enables REST services to roll out updates and changes without causing end-client breakage. If a new version of the service API is be released, clients who are not ready to use the new version can specify a preference for the old version. Clients can also request a catalog of available versions; each version in the catalog is marked with a status, such as CURRENT or DEPRECATED, which the client can use for guidance in deciding which version to use.

General filter information

Filter name: versioning

Filter configuration: versioning.cfg.xml

Released: prior to 2.x

Prerequisites 

Headers: The Versioning filter can use the Accept header to determine the endpoint which it will route, but it is not strictly required.

Preceding filters: No other filters are required for use with the Versioning filter. 

Standard filter order: If you are using other filters in your system model configuration, refer to the standard filter order table to determine where to place the Versioning filter.

Basic versioning configuration

  1. To enable the Versioning filter, add the filter to the system model.
    1. Add <filter name="versioning"/> to the list of filters in /etc/repose/system-model.cfg.xml
  2. Create versioning.cfg.xml in /etc/repose with the desired configuration.

Example

Within the  version-mapping element:

  • Configure the id to identify the version name and define the URI match to determine the version.
  • Configure the pp-dest-id to identify the service domain destination that will answer the versioned requests that match this version mapping.

 

Optional configurations

Routing based on URI

  1. Create a system-model.cfg.xml with more than one endpoint:

     2. Create a versioning.cfg.xml with id values representing the URI to route by:

   3. Now when hitting /api1 Repose will route to endpoint1 in the destinations list and hitting /api2 Repose will route to endpoint2 in the destinations list.

For more routing information, see Routing options.

Media type

You can configure the Versioning filter to look at the accept header if the version information in not in the URI.

Add the <media-type> element to your versioning configuration to use the media type specified in the accept header if the version information is not present in the URI.


The following example shows a valid sample request and a section of the Versioning filter configuration that uses the <media-type> element. 

This is a valid request that could pass through the Versioning filter. The request does not define the version type.

Request
curl repose.com/blah -H 'Accept:*'

 

This section of the versioning configuration shows two defined <media-type> elements. (Your configuration may have numerous <media-type> elements listed.) The request will be directed to the endpoint that is defined by the matching media type.

Configurable parameters 

XML schema definition

Example configuration

The versioning.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the system model configuration.

Element

Attribute

Required/

Optional

DescriptionVersion
<versioning> -RequiredSpecifies the sub-elements and attributes to define your versioning configuration. 

json-formatOptionalSpecifies the format of the JSON output when describing the list of versions or a single version.  The default and standard format is "COMPUTE".  The new available format is "IDENTITY".8.0.1.0
<versioning-mapping> -RequiredDescribes the available versions to the requester. 

idRequiredUniquely identifies the version mapping within the configuration. 

pp-dest-id

RequiredIdentifies which service domain destination will answer to versioned requests that match this version mapping. The service domain destination is defined within the system model. 

statusOptional

Describes the current operational state of  the given service version.

The list of valid values are: DEPRECATED, ALPHA, BETA, CURRENT
Note: When the json-format is set to IDENTITY, these will be translated to "deprecated", "alpha", "beta", "stable" in the JSON response.

 
<media-type> -OptionalDescribes the media type of content it can understand and return. Media types must include as human-readable attributes both their base type and the complex type. 

baseRequired only if using media-type.MIME type without versioning or vendor information.The base of a given media type describes the simple MIME type that then a more complicated media type can be derived from. These types are basic and provide no namespace or version specific data and are only provided as a convenience. Because of this the base attribute is declared as optional. 

typeRequired only if using media-type.Describes the MIME specific identifier of the media type in question. This identifier should include a vendor namespace (See RFC 2048)  as well as a version suffix. 

Return codes and conditions

Handling Un-Versioned or Bad Requests

In the case that a request has been made that can not be mapped to a valid service version, the Versioning component will return a 300 (Multiple Choices) as well as a full service version catalog that can be used to make the correct request. The resulting Atom links within the service version catalog will retain the incorrectly-requested resource in an attempt to correctly link the requester to valid, versioned representations.

Example
Request
Response
1GET /root/1234/path/to/widget/12 
Accept: application/xml
300 Multiple Choices 
with info of all available versions in xml format.
2GET /root/1234/path/to/widget/12 
Accept: application/json
300 Multiple Choices 
with info of all available versions in json format.
3GET /root/v1.b/path/to/widget 
Accept: application/xml
300 Multiple Choices 
with info of all available versions in xml format.
4GET /root/v1.b/path/to/widget 
Accept: application/sjon
300 Multiple Choices 
with info of all available versions in json format.

Request headers created

No request headers are created.