API versioning

[mattkuznicki-ll]

Let's discuss API versioning. In the comments on https://github.com/Lasagna-Love-Portal/bechamel-api/pull/18 there are two votes for a major versioning scheme on the routes, e.g.

/v1/login

How do we want to do versioning?

[mkantzer]

I think there's 2 major options here:

1. version the whole API together (v1/[login, signup, whatever other paths])
2. version per components/domains (login/v1/, signup/v2, ...)

I'd tend to stick with 1.: it gives us significant freedom with organizing the backend however we want, without really needing to worry the front end about it. 2. could have us making a lot of assumptions about organization that may not stay true.

There's also a world where we do both (v1/login/v1/), but that's.... gross? I'd rather just bump the global version more often.

[mattkuznicki-ll]

I'm more in favor of (1) - /v#/endpoint - than (2) personally as well. Would like to version efforts up to our v1 initial launch as v0 to make it clear things are in flux.

[patmejia]

• Global Versioning (Our Recommendation @mattkuznicki-ll, @mkantzer):

  • Simplicity & Flexibility: Keeps things straightforward across the API and offers adaptability without fussing over individual components.
  • Pre-launch Versioning (v0): On board with Matt's take on using v0 before the v1 launch, signaling ongoing development.
  • Ease of Maintenance & Alignment with Semantic Versioning: Cuts down on management headaches and aligns with clear communication, predictability, and integration practices.

• Component-Based Versioning (Not Our Preference):

  • Potential Pitfalls: While allowing for granular control, it could lead to complexity and confusion.

• Key Thought:

  • Semantic Versioning with Global Approach: Puts us on solid ground, ensuring clear and consistent changes in sync with the broader development ecosystem.