Versioning

Versioning

HTTP Request

We want to allow you to configure versioning strategies on your API.

We'll allow all the wrong ways described in this article: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/. And some other, even worse ways.

1. URL

GET /v1.0/people/123

2. Custom request header

Configurable custom request header.

Version: 1.0
GET /people/123

3. Accept header

Accept: application/vnd.yourapplication.v2+json
GET /people/123

4. Querystring

Configuration querystring parameter.

GET /people/123?version=1.0

Config

All should be configurable in the endpoint config. Config object something like this:

VersioningStrategy = new VersioningStrategy
{
    AllowUrlVersion = true,
    CustomRequestHeaders = new[] { "Version", "X-Version" },
    AcceptVendorHeaderTypes = new[] { "yourapplication" }
    QuerystringParameters = new [] { "version", "_version", "api-version" },
    NoVersionBehaviour = NoVersionBehaviour.LatestVersion // VersionOne, ThrowNotFound
}

C# Stems

In Stems, we want to be able to deprecate fields and add new fields in specific versions.

A new Version attribute can use parameters for a Comparison enum and a string version number. The enum could be the ComparisonOperator declared in Firestorm.Core.

Here's an example of splitting Name into FirstName and LastName if the client requests 1.1 or higher.

public class ArtistsStem : Stem<Artist>
{
    [Get]
    [Identifier]
    public static int ID { get; }

    [Version(Comparison.LessThan, "1.1")]
    public static string Name { get; }

    [Version(Comparison.GreaterThanOrEqual, "1.1")]
    public static string FirstName { get; }

    [Version(Comparison.GreaterThanOrEqual, "1.1")]
    public static string LastName { get; }
}