API Versioning
Now that we have defined our routes, models, and policies, it is time to spice things up.
You may have noticed that all routes created by ChiselStrike have /dev/ as part of the route.
That's because ChiselStrike makes API versioning a first-class citizen: everything you deploy to
ChiselStrike is deployed as part of a version.
Creating a new version
Versioning is a production-oriented workflow.
When starting to play with versions, it is advisable that you turn off chisel dev, as it will
keep trying to push changes to the dev version. Start your server with chisel start instead,
and push your changes manually with chisel apply.
If you installed through npm, the chisel utility is available through npx chisel. Just
substitute npx chisel in the examples.
Versions are an optional parameter to the chisel apply command.
Creating a version creates a fully independent branch of your backend.
Let's now create a new API version, called experimental. In the same directory,
type
chisel apply --version experimental
and chisel apply reports:
Applied:
1 models
Now let's try comparing the two routes.
If we invoke the new experimental API version:
curl localhost:8080/experimental/comments
The curl command reports no data:
[]
However, we can still invoke the old dev version of the endpoint:
curl localhost:8080/dev/comments
and the curl command reports all the old data, untouched:
[{"content":"First comment"},{"content":"Second comment"},{"content":"Third comment"},{"content":"Fourth comment"}]
The versions now can evolve independently.
Populating from an existing version
Although you can create a new fully independent version and build it up by adding data through your routes, it is sometimes useful to populate your new version from some other existing version.
This can be done with chisel populate:
chisel populate --version experimental --from dev
Assuming experimental is empty before the population starts, you should see that the experimental version
now holding the same data as dev.
If you invoke the /experimental/comments endpoint:
curl localhost:8080/experimental/comments
The curl command reports:
[{"content":"First comment"},{"content":"Second comment"},{"content":"Third comment"},{"content":"Fourth comment"}]
Use-cases for API versioning
API versioning is useful for:
- Development/preview branches,
- Supporting older and newer clients, once version linking in supported.