4 ms·

What does a codebase look like with these API versioning exactly? I feel like code bloat would be hard to maintain. Obviously I could take two endpoint handler

What does a codebase look like with these API versioning exactly? I feel like code bloat would be hard to maintain. Obviously I could take two endpoint handlers that have the same functionality and move their behavior into a shared function, but there's also tests to consider. As time went on, I'd have a pile of tests running against seemingly random versions. Eg, `test_blog_create()` might test v1 and v2 of the API as that specific endpoint didn't change, but suddenly in v3 the API _does_ change, so now I need to write a slightly different test to handle that new functionality. `test_blog_create_v3()` or w/e. I'm not arguing against it, merely noting what I've previously thought about as problematic for implementing versioned APIs. Thoughts on how best to manage the code base?

Waterluvian 7y ago
Versioning is hard. Versioned APIs are very hard. I'm in an especially tricky spot because we've got customers that might refuse to upgrade our product for years and years, if ever. Two approaches I've taken, with a blogpost worth of thoughts on them: 1. Every version is a whole new database/webserver stack. You shut the oldest one down when the last customer migrates off it. The bloat is real, but it's dead simple and it works. 2. A single database with a webserver that exposes all the versions. The contract is that the database shall not undergo destructive migrations. Only additive migrations. Or if you must, modify schema in a way that you can deterministically generate every previous API's view. Again, discard older versions when the last customer has been migrated off. I'm sure you can immediately smell some problems with either of these approaches. Sacrifices are definitely made.
- emilsedgh 7y ago
  Every version is a whole new database/webserver stack. You shut the oldest one down when the last customer migrates off it. The bloat is real, but it's dead simple and it works. That means data is different between API versions?
  - Waterluvian 7y ago
    Yes. But that works. Becuase a customer's data lives in only one version. When the customer upgrades their data gets migrated. Weird. Dead simple. Works.
Corazoor 7y ago
There is definitely multiple ways to handle that, but splitting your API into frontend and backend seems to be a common and good approach. The backend is basically the "real" internal API, subject to changes. The frontend consists of nothing more than forwarding functions, that take their input from the outer world and translate it to backend API calls. How you organize Code reuse depends on the language, but inheritance is not a bad way to do it, although you might run into trouble with the size of your hirarchy. You can circumvent that with maps of functions/lambdas, like prototyping in Javascript. For testing you then have your usual set of tests for the backend, but for the frontend you just test if the translation between public and internal API is correct. Very easy to test for in most cases. If you then organize your tests exactly like your frontend Version, i.e. some kind of inheritance, you only ever have to add tests for the changes in your new Version. It is definitely more work than just having one ever changing API, but it's not that much of a hassle imho.

Waterluvian 7y ago

Versioning is hard. Versioned APIs are very hard. I'm in an especially tricky spot because we've got customers that might refuse to upgrade our product for years and years, if ever. Two approaches I've taken, with a blogpost worth of thoughts on them: 1. Every version is a whole new database/webserver stack. You shut the oldest one down when the last customer migrates off it. The bloat is real, but it's dead simple and it works. 2. A single database with a webserver that exposes all the versions. The contract is that the database shall not undergo destructive migrations. Only additive migrations. Or if you must, modify schema in a way that you can deterministically generate every previous API's view. Again, discard older versions when the last customer has been migrated off. I'm sure you can immediately smell some problems with either of these approaches. Sacrifices are definitely made.

emilsedgh 7y ago
Every version is a whole new database/webserver stack. You shut the oldest one down when the last customer migrates off it. The bloat is real, but it's dead simple and it works. That means data is different between API versions?
- Waterluvian 7y ago
  Yes. But that works. Becuase a customer's data lives in only one version. When the customer upgrades their data gets migrated. Weird. Dead simple. Works.

Corazoor 7y ago

There is definitely multiple ways to handle that, but splitting your API into frontend and backend seems to be a common and good approach. The backend is basically the "real" internal API, subject to changes. The frontend consists of nothing more than forwarding functions, that take their input from the outer world and translate it to backend API calls. How you organize Code reuse depends on the language, but inheritance is not a bad way to do it, although you might run into trouble with the size of your hirarchy. You can circumvent that with maps of functions/lambdas, like prototyping in Javascript. For testing you then have your usual set of tests for the backend, but for the frontend you just test if the translation between public and internal API is correct. Very easy to test for in most cases. If you then organize your tests exactly like your frontend Version, i.e. some kind of inheritance, you only ever have to add tests for the changes in your new Version. It is definitely more work than just having one ever changing API, but it's not that much of a hassle imho.