Comment by simonw | Hacker News Reader

Comment by simonw | Hacker News Reader

A lesson I learned working with microservices that are deployed independently of each other is that you need a policy that ALL changes must be backwards compatible with existing clients.

This sounds crazy, but it's essential if you can't guarantee that you can atomically deploy a new service version AND any other services that call it.

Creating backwards compatible releases means sticking to some rules, things like:

- you can add fields but you can never delete them

- you can add new methods but you can't remove old ones

Having really detailed logging helps a lot. If you want to deprecate a method you can remove it from calling clients first and then use the logs to confirm it isn't being called any more before removing it from the service.

It's a lot if work, and teaching a large engineering team how to be productive in this kind of environment is decidedly non trivial.

Never say never.

Adding fields or methods is easy. You can do it at any time.

Removing them is difficult. You must first go through a long deprecation cycle and ensure ALL clients are updated.

You need good logging AND good monitoring and analysis of the logs in both client and server to be able to detect access to removed features.

A coworker pointed out that this is a huge point in favour of GraphQL: because it forces clients to explicitly ask for every field you can log those queries and use them to spot when a field is no longer in use.

Actually, if the server knows the client version, he can downgrade returned data to the client in the version he expects. That way, adding, renaming and removing fields should not be a showstopper, assuming methods stay as generic as possible.

Alternatively you could provide different API versions at the same time and keep the old ones running, as long as they are called.

While you can build machinery to do this. It is far easier to not. If you substantially want to change your api, just make a new one. Much easier to track migration between endpoints than it is versions in an endpoint.

And, in general, don't focus on generic methods.

The more specific a service method, the better. The less it does, the better. Don't have an "order pizza" api. Have a "start order", "add to order", and "complete order" api. If it helps, have multiple add methods. The parameters to add a pizza can and should be different from a salad. Even the pizza may be better served with partial service calls to start and complete.

Reply on news.ycombinator.com