[ComputerGuru]

I upvoted because I'm curious to hear what others are doing. We typically make sure to only make such breaking changes where either the now-required value or a sane filler value could be used. If it's the same API for the same purpose, it's usually not a stretch to assume the values for a new field are derived from some combination of an old field or else are primitive components of an old field such that they can be deduced and stubbed in your transition layer (or calculated/looked-up/whatever one-by-one as part of a bulk migration script during the transition). If your v2 is so drastic of a breaking upgrade that it bears no relationship to v1, I imagine your SOL and probably should have thought out your v1 or your v1-to-v2 story better, if only for the sake of the poor devs using your API (and you probably need separate tables at that point).

For other fields like your example of `avatar_url` I would use a placeholder avatar for all legacy users (the grey anonymous snowman profile comes to mind).

[ceeker]

Thanks. This is a fair point. I made up the example only to illustrate the idea. Since Stripe is considered some sort of benchmark here I was curious to see how they tackle all the learnings they will have over time...I feel it is very hard to think through all the future cases especially when you are just about starting out with your product.

For example, in financial services and insurance, regs change and what data we need to collect change and sometimes their dependency will change. I am curious what's companies that have grown substantially had to do to their APIs.

[ComputerGuru]

No worries, I understood it was a throwaway example that shouldn't be looked at too closely. You just have to remember that your DB isn't a model of what you want to require from your customers but rather a model of what you actually necessarily have and don't have. A field like the ones you're talking about shouldn't be marked non-nullable in the database if there's a chance you actually don't have that data (and when you are suddenly required to collect something you didn't have before, you're not going to have it).

Coming at this from a strongly-typed background, you acknowledge the fact that despite new regulations requiring a scan of the user's birth certificate in order to get an API token, that field can't be marked as non-null if you don't in fact have all those birth certificates. You are then forced to handle both the null and not-null cases when retrieving the value from the database.

So your API v2 can absolutely (in its MVC or whatever model) have that field marked as non-null but since your API v1 will still be proxying code to the same database, your db model would have that field marked as nullable (until the day when you have collected that field for all your customers).

If a downstream operation is contingent on the field being non-null, you are forced to grapple with the reality that you don't have said field for all your users (because of APIv1 users) and so you need to throw some sort of 400 Bad Request or similar error because (due to regulations) this operation is no longer allowed past some sunset date for users that haven't complied with regulation XYZ. In this case, it's a benefit that your db model has the field marked as null because it forces you to handle the cases where you don't have that field.

I guess what I'm saying is the db model isn't what you wish your data were like but rather what your data actually is, whether you like it or not.

[christophilus]

I think Stripe was originally built on Rails (can’t find anything to confirm that at the moment). But my guess is they enforce things at the app layer, since Rails didn’t really provide a good way to enforce things at the DB layer originally. They support very old API versions by transforming requests backwards and forward through a list of API version transforms, which also suggests to me that this sort of thing is enforced at the app layer rather than the DB.

[martypitt]

Hey

We're working in this space at the moment, (eliminating the pain from breaking changes in APIs) and looking to get feedback on what we're building.

We're all from banking backgrounds, so understand the reg headaches you're talking about.

Can we chat?