Prevent API breaking changes

Question

We have REST-API based on ASP.NET WebApi. And we distribute bia nuget .net client library to communicate with our API.

WebApi controllers and client library shares client models. If I add some new optional field to model - it's ok, but when in some new release we accidentally add new enum value on API, previous version of client will thrown exception if it receives new enum value.

So, it there any way to check backward compatibility of API and client and prevent breaking changes?

Answer 1

This looks like a typical use case for REST API versioning.

You can will need to support different versions in API and then have your client specify which version it is requesting.

Different mode of versioning are:

1. URL Versioning

   api.example.com/v1

2. Versioning using header if you want to keep a single URL for a resource

   Accept:Version: v1

Refer microsoft api versioning guideline here .

The library is pretty well documented.

Answer 2

when in some new release we accidentally add new enum value on API, previous version of client will thrown exception if it receives new enum value.

Based on @mtkachenko's answer: Write integration tests where all supported versions of your client (also 3rd party clients, if any) are tested against the release candidate (or dev/staging/QA environment) of your API.
If the tests fail with any of these client versions, then your API change is incompatible.

Plan for extension - eg in JSON, prefer objects over plain strings/numbers, so you can add more fields in the future.

Also document expected future extensions, so developers are aware that eg

• a particular field may get additional values in a future API version, and unknown values can be treated eg like the existing value XY.
• a particular array field which today always has one element may in the future have multiple elements.

add new enum value

Zalando suggests to never extend enums that are used in responses:
https://opensource.zalando.com/restful-api-guidelines/#107

You may also find more useful information there, I think their document contains lots of good principles and ideas:

• https://opensource.zalando.com/restful-api-guidelines/#general-guidelines
• https://opensource.zalando.com/restful-api-guidelines/#compatibility
• https://opensource.zalando.com/restful-api-guidelines/#deprecation

Answer 3

In this particular case: don't use enum in client libraries. This situation will happen every time when you need to extend this enum. I suppose you don't want to make a new version of API for each such change. Inside your client you should accept string values and then try to parse it. If it's parsed - OK, if it's not - set YourEnum.None .

In general: to prevent breaking changes you should create integration tests and run them on your CI server. If you add a new rule in api - existing integration tests shouldn't fail. At the same time there is no 100% guarantee. It depends on how you are meticulous while writing integration tests. The same story as for unit testing actually.