Skip to content

API versioning

All IAppServices and Controllers are versioned server-side, hence they are required to be invoked with a specific version from client-side, otherwise a Bad Request (400) error is going to be raised at runtime.

Even if no version's been defined for the IAppServices or Controllers at server-side, the MVC Routing infrastructure will assign them a default one. By default, version v=1.0 will be assigned in those cases.

If no version information was provided by the client, the framework will refuse to process it. This statement rules either for ordinary Controllers as well as for IAppServices.

Keep in mind that, even though a default version can be assigned server-side, there is no implicit default version assumption at client-side. Bad Request responses are always returned for invocations where version information is missing.

Important

The rules stated here apply mainly for internal APIs, those that are consumed internally by services inside the boundaries of the Suite, or by clients off the Suite boundaries which are under our entirely control.

Please refer here to get more information about api versioning.

Version-by-namespace strategy (Server-side)

At server-side the version information is taken from the namespace in which the Controller or IAppService is defined. The developer has to do nothing to have it working, the framework will automatically grab the proper version information from the namespace in which the Controller or IAppService is defined.

Warning

Ensure the IAppService or Controller is placed in a namespace where a version value can be extracted from. Even though, the server is able to assign a default version when no one can be extracted, at client-side invocation will fail

Versioning when using AppService Proxies

When using IAppService proxy at client-side, meaning that you've injected an IAppServiceProxy<TAppService> instance, you have to do nothing for the version selection to get done, the Suite Framework will set the version properly taken from the namespace where the IAppService is defined in.

Given an IAppService contract:

C#
1
2
3
4
5
6
7
namespace ITsynch.Suite.SomeService.Application.V2 {

    public interface ISomeService : IAppService
    {
        Task<SomeResultOutputDTO> DoSomethingAsync(CancellationToken ct);
    }
}

By injecting an IAppServiceProxy<ISomeService> instance, the Suite framework will be aware of the V2 present in the namespace where the ISomeService is defined, taking care of adding the necessary header to select the V2 version properly.

Manually Versioning by media-type

If using AppService Proxies is not possible, please contact the Suite Team. That being said, it is possible to specify the version manually when executing a request. To specify the version, you must use Accept header for those request having no payload or content (such as get or delete ones), whereas for request having payload or content (such as post and patch ones) the version must be specified in Content-type header.

Development process

Strive to not create new api versions whenever possible, try to make needed changes to the public API, and refactor the affected projects, at once. Whenever this process couldn't be carried on, you will need to create a new API version. This way you let the chance to other projects/teams working in the monorepo to address the update process with the new API version.

To summarize, bear in mind these aspects when creating new API versions:

  • Do create a new version only when breaking changes cannot be implemented at once in the monorepo, when the adoption of the new API must be deferred over time.
  • Do use [Obsolete] attribute for those public symbols that became obsolete. These obsolete assets must be short-lived and be removed as soon as possible. They are likely to be removed in the version after the one in which they has been marked as obsolete.
  • Do not extend previous assets to build up the new version, start off by copying all the needed assets, changing the API surface, and finally versioning them correctly.
  • Do Use semantic versioning (SemVer) when labeling new versions. Refer to the criteria defined by SemVer versioning to evolve the API appropriately, giving consumers right information to make good decisions. Please refer tp this link to know more about SemVer.
  • Do arrange your versioned assets in project's folder identifying the version properly.
  • Do Use repository announcements to let other teams to be on-track with changes.