API development - Exposing new version VS updating current version

Question

Context

There is a back end and a front end team.

Back end exposes an endpoint to the front end app:

PATCH car/{carID}/tire

Problem

I want to update the aforementioned PATCH request functionality which will change the request's body .

Solution

There are two options:

• Change the current endpoint and ask the front end team to update the payload on the request's body.
• Create a new endpoint car/{engineID}/v2/tire , so the front end team can switch to this version when they see fit.

Question

I prefer the second approach, as it allows the two teams to work asynchronously . The short coming here is that every time I will need to update this endpoint I will need to expose a newer version ??

In which scenarios should I follow the first approach, which actually breaks the current system ? Does this violates the open-closed principle ? Does the open-closed principle apply here ? Should I follow this principle in this scenario ? Is there another alternative to the two aforementioned methods ? Is there a design flaw that resulted in this scenario ?

Answer 1

Breaking changes vs non breaking changes

Your endpoint and the resources exchanged over it basically define a contract between the back-end and the front-end.

You can have some changes done to the endpoint without breaking the contract and affecting your front-end. For example, you can have new data added to the response but without removing the already existing data, your endpoint might accept optional parameters, etc. These kind of changes don't affect your front-end because it's extra stuff to what is already known and expected.

Breaking changes will break the contract, so the front-end will need to change. Breaking changes include, for example, changing property names or their types, adding mandatory parameters for the endpoint, etc.

What approach you eventually use depends on what kind of changes you did. And this is a large topic about API versioning, and can be done any number of ways, like for example.

The way to choose an approach is to talk with your front-end team. Ask them how they prefer to be notified of changes and how they want to implement them. Then together decide what works best for everyone involved.