ServiceStack REST API Versioning practical questions

Question

Our team is looking for a convenient way to implement versioning in our ServiceStack API implementation.

I've read the articles:

• ServiceStack: RESTful Resource Versioning
• https://docs.servicestack.net/versioning#implicit-versioning
• ServiceStack versioning - how to customize the request deserialization based on versioning

But I don't get a practical way of working for our system.

I've made a list of changes that could happen in the lifetime of the application:

No breaking changes:

1. Add a new service
2. Add a new property to an existing request DTO
3. Add a new property to an existing response DTO
4. Add a response to an existing (void) request DTO

Breaking changes:

1. Remove a service. This breaks the client if the service will be called.
2. Remove a property of an existing request DTO. May not break, but it will be ignored in the service, thus the response may differ.
3. Remove a property of an existing response DTO. This breaks if the calling client uses the property.
4. Remove HTTP verbs. Replace Any with the desired GET, POST, PUT, DELETE, etc. verbs.
5. Different semantic meanings of service. Same request name, but different behaviour.

Combinations of breaking changes:

1. Renaming a service. Thus adding a new service and removing the old one.
2. Rename a property of an existing request DTO.
3. Rename a property of an existing response DTO.
4. Split up property of an existing request DTO.
5. Split up property of an existing response DTO.

We deliver a new release twice a year. Our naming scheme is very simple and looks like: 2020.1.0 2020.2.0 2021.1.0 2021.2.0 xxxx.x.0

We have service packs within the releases. Service packs cannot contain database changes and breaking API changes. The naming scheme is simple: 2020.1.1 2020.1.2 2020.1.3 2020.1.x 2021.1.1 2021.1.2 2021.1.x

Our client and server apps are delivered at the same time on a customer site. Thus with our software delivery, we update all the software at once. No problems so far.

The problem we have has to do with partners and customers who are using the API and may face breaking changes.

We do not want a partner or customer to force their software simultaneously when we update our software at the customer site. There should be some grace period where the partner or customer can update their clients of our API.

We have the following idea:

1. Partner en customer client develops against a specific version of our API by giving the release version number. I.e. 20201 (=2020.1) in the header, url or querystring parameter (which is best/supported?).
2. ServiceStack in our implementation should notice the version specified by the client and let it discovers only the available APIs which belong to that version. Thus if our software is version 2021.2, then it should 'downgrade' its API exploration to the specified version. The idea is that every request DTO and response DTO has a version property with a similar versioning strategy as with aspnet-api-versioning (https://github.com/dotnet/aspnet-api-versioning/wiki).

I've tried to experiment with the current capabilities of ServiceStack in the following example.

// ServiceStack configuration in AppHost
public override void Configure(Funq.Container container)
{
    SetConfig(new HostConfig
    {
        ApiVersion = "20231"
    });

    var nativeTypes = GetPlugin<NativeTypesFeature>();
    nativeTypes.MetadataTypesConfig.AddImplicitVersion = 20231;
}

public class Project
{
    public int ID { get; set; }
    public Guid GlobalID { get; set; }
    public string Number { get; set; }
    public string Name { get; set; }
    public string Description1 { get; set; }
    public string Description2 { get; set; }
    public string City { get; set; }
    public bool Active { get; set; }
}

[Route("/projects", "GET POST")]
public class GetProjects : IReturn<List<Project>>
{
    public string SearchCriteria { get; set; }
    public int PageSize { get; set; } = Constants.DefaultPageSize;
    public int PageNumber { get; set; } = Constants.DefaultPageNumber;
    public string OrderBy { get; set; }
}


public class ProjectV20231
{
    public int ID { get; set; }
    public Guid GlobalID { get; set; }
    public string Number { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public string City { get; set; }
    public bool Active { get; set; }
}

public enum OrderByDirection { Asc, Desc }
public class OrderByElement
{
    public string Field { get; set; }
    public OrderByDirection Direction { get; set; }
}

[Route("/projects", "GET")]
public class GetProjectsV20231 : IReturn<List<ProjectV20231>>
{
    public string SearchTerm { get; set; }
    public int Offset { get; set; }
    public int Limit { get; set; }
    public List<OrderByElement> OrderBy { get; set; }
    public bool? Active { get; set; } = null;
}

public class ProjectsService : Service
{
    public List<Project> Get(GetProjects request)
    {
        var result = new List<Project>
        {
            new Project() { Name = "2020.1" }
        };
        return result;
    }

    public List<ProjectV20231> Get(GetProjectsV20231 request)
    {
        var result = new List<ProjectV20231>
        {
            new ProjectV20231() { Name = "2023.1" }
        };
        return result;
    }
}

We have a lot of existing services without any versioning. In this example that is GetProjects request and Project response. As long as there are no breaking changes we could keep the request and response DTOs without any version specification.

When we have a redesign of our API, we could introduce a new request and/or response DTO with the name extension V[ReleaseAndServicePackVersion], for example, GetProjectsV20231 and List ProjectV20231.

If partners or customers programmed against the 2020.1 version, then this should be set in the ServiceStack client or querystring:

client.Version = 20201;
client.Get(new GetProjects());

/api/projects?v=20201

If partners or customers want to use our new version, then they should update the version number and repair any breaking changes.

client.Version = 20231;
client.Get(new GetProjects());

Note: I still use GetProjects, although this probably won't work because they should use GetProjectsV20231 instead. But why should we specify the Version property of the client than any more?

If they don't use our DTOs, but are using the querystring approach, then the call should look transparent (although it is not, because the response is different).

/api/projects?v=20231

Questions:

1. Can we let ServiceStack show only the services which correspond to a specified version of the API? For example /api?v=20231 must only show the 2023.1 compatible services.
2. Is there a more convenient way to solve the versioning for our system? For ASP.NET a lot of research is already done, see https://github.com/dotnet/aspnet-api-versioning/wiki. Could this also be implemented in ServiceStack?
3. Should we also rename the GetProject request and Project response to GetProjectV20201 and ProjectV20201, otherwise ServiceStack don't know that these request and response are now version specific.
4. If 2023.2 version is out and there is no breaking change for GetProjects20231 then GetProjectsV20231 should be used, because it is the latest available version for the request. How can we configure/program ServiceStack to do that?

Answer 1

This Sounds like it's looking for a magic bullet to version typed APIs when there really isn't one, existing Typed clients are going to expect their Typed Request and Typed Response to remain the same which means the server needs to forever fulfill that API contract for as long as you want to make legacy versions of the Service available.

Versioning in Dynamic Languages

IMO dynamically routing requests to different based on a ?v=xx query parameter is only really feasible in dynamic languages who are better able to use model transformers to map how existing requests map to newer requests, call the newer API implementation then map their responses back to existing API contracts of existing Services, in ServiceStack it would look something like:

public class MyServices : Service
{
    public object Any(GetProject request)
    {
        var v2Request = request.ConvertTo<GetProjectV2>();
        var v2Response = Any(v2Request);
        return v2Response.ConvertTo<GetProjectResponse>();
    }

    public object Any(GetProjectV2 request)
    {
       //...
       return new GetProjectV2Response { ... }    
    }
}

This would take dramatically less effort to maintain in dynamic languages which can do the transformation with just mappers without introducing new types.

Versioning in Typed APIs

But adding new breaking API versions in typed APIs is going to result in an explosion of new API Request/Response, DTO and Data Model Types that's going to become less and less maintainable the more versions you need to support which is why the recommendation is to evolve your services by enhancing existing Services defensively so existing APIs can handle both old and new Requests.

API Version Info

Populating the Version in Request DTOs is to make it easier for APIs to determine which client version sent the request instead of trying to infer the version based on the heuristics of what parameters were sent with the API Request.

But if you want to make breaking changes with different Request/Response schemas you're going to need to create new Typed APIs. Given the effort to maintain multiple different API versions, making breaking changes should be a last resort. But if I wanted to enable it I'd put the version in the /path/info so it's given a permanent URL that wont change, e.g:

[Route("/v1/projects")]
public class GetProjects {}

[Route("/v2/projects")]
public class GetProjectsV2 {}

I'd disregard applying your external software versioning scheme to APIs (e.g. GetProjectV20231) and just version each API independently, primarily focusing on evolving them with backwards-compatible changes, and only adding new APIs when breaking changes are necessary.

Versioning Code Bases

New software releases could be updated to have the latest version of your APIs maintain the optimal name for the latest API e,g:

[Route("/v1/projects")]
public class GetProjectsV1 {}

[Route("/v2/projects")]
public class GetProjects {}

Newer versions of your software could rename the Server DTOs to their optimal names which should still support existing clients using existing DTOs since their schema contracts remain the same. They'll only need to update their clients when they want to use your software's latest typed API DTOs.

API Grouping

As for grouping your APIs I'd recommend using Tag Groups to group them, which can utilize your software versioning scheme to annotate APIs available in different versions, e.g:

[Tag("v2022.6")]
[Route("/v1/projects")]
public class GetProjectsV1 {}

[Tag("v2023.1")]
[Route("/v2/projects")]
public class GetProjects {}

[Tag("v2022.6"),Tag("v2023.1")]
[Route("/v1/projects/{Id}")]
public class GetProject {}

This will allow clients to browse APIs available in different versions in Metadata Pages as well as the built-in API Explorer.

It's also supported in Add ServiceStack Reference which can be used by clients to only generate DTOs for APIs in different versions.