I have a public facing REST API and SDK with multiple resources being managed: /api/v1/foo and /api/v1/bar. Both are currently version 1.
I want to make some breaking changes to both endpoints including making them more consistent (headers, date formats, etc) but since I work in an Agile environment, I will be making changes to one endpoint, releasing it, and then changing the other later. (Assume that foo gets enhanced first)
How should I handle versioning the endpoints? What are the pros and cons of different options of versioning? Are there any additional options besides these?
Option 1:
Release /api/v2/foo with new changes. Leave /api/v1/foo and /api/v1/bar deployed. Consumers that want to use the new features of /api/v2/foo would send API requests for foo to /api/v2/foo while requests for bar still get sent to /api/v1/bar. Some requests are v1 while others are v2.
Eventually I release /api/v2/bar and consumers transition off of v1 entirely so all requests are v2.
Option 2:
Release /api/v2/foo with the new changes. At the same time, I also release /api/v2/bar which is just an alias for /api/v1/bar. Consumers that want the new features stop pulling in the v1 SDK and replace it v2 SDK. All requests get sent as v2.
Eventually when I complete the enhancements to the bar API, I follow the same process above and change everything to v3.