This is part of a multi-part series on how to version your API.

As previously discussed, the whole point of versioning is to manage change so you can evolve your API without breaking your client's implementation. In order to do this, changes that will "break" will your client's implementation warrant a new version. But what is and is not "breaking" can be tricky.

Is your change additive and backwards compatible?

In general, adding new "things" to your API should be considered safe. These include:

• Adding new RESTful operations
• Adding new resources
• Adding fields on existing objects
• Accepting new query params
• Accepting new, optional fields on POSTs
• Accepting new, optional headers
• Modifying internal implementation details such as how a value is derived

You should consider the specifics of your own API as every API has nuances. But it is reasonable to expect clients to implement in such a way that additions are simply ignored when they come online and implementation details are not hardcoded.

Conversely, changes that are clearly breaking or backwards-incompatible generally include modifying how things are represented.

Some examples include:

• Changing the field types (eg turning an integer field to a string field)
• Making something required such as a field in an POSTed record (eg a "name" field on User) or a header (eg a Version header)
• Removing something such as an operation or a previously required field
• Making something non-nullable now nullable
• Modifying the meaning of a field (eg changing a weight field from pounds to kilograms)

Some gray areas

In between the obvious examples, there are some tricky gray areas. For example, let's say your User records have a picture_url field which has always pointed to an S3 image and you wanted to host your images elsewhere. You could argue that a client shouldn't make any expectations about what that URL looks like...just that it points to an image. But you should be aware that clients may have hardcoded such an expectation and perhaps even for a legitimate reason (perhaps their code was operating behind a firewall and had white-listed S3).

It's in these situations that you should keep in mind Hyrum's Law:

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.

No, you it is not your job to prevent every client against hard-coding such implementation details, but it is your job to use your best judgement. Consequently, it is best to always provide comprehensive documentation, proactively communicate to your clients, and strive to make change less painful for your clients.