API Versioning with The Phoenix Framework

So you have the foundations built for a Phoenix project and now you want versioning to go with your shiny new API. Thankfully, with a bit of clean folder structuring and clearly defined routing, Phoenix makes this pretty simple. Let’s get started!

And one last thing before we begin, I want to clarify the software versions I used while writing this:

First things first, let’s move away from the standard, single “controllers” folder and add in a couple of nested folders to support our versioning. Within the stock “controllers” folder we’ll want a new “api” folder as well as, within our new api folder, a “v1” folder to hold our initial controllers. Here’s what that looks like:

In the image above you can see an example of how the API might grow in the future. This lets us support multiple versions of a resource and helps keep things clean and compartmentalized.

Phoenix, like many frameworks, makes use of Views and in order to best adhere with “convention over configuration” we’ll need to structure our views folder similarly to the way we structured our controllers folder.

Routing in Phoenix is super easy and friendly. Open your project’s “router.ex” file to get started. Now is the time to briefly mention “scopes” and what they represent within the context of the router file. Scopes are the preferred, and probably easiest, way to define a set of common route prefixes. This means we can prepend a common naming convention to a number of our routes — perfect for APIs and versioning.

I’ve gone ahead and modified the user data within my controllers and the views so that v2 returns a bit more data than v1. You can see the different responses below:

That’s it! Super easy. It’s just a matter of creating folders that you feel comfortably fit the naming conventions appropriate to your API. Once that’s done, make sure the module naming conventions logically follow so Phoenix can find the Elixir files it needs. Finally, setup your routes with the scoping that makes the most sense for you. Now you have different versions of API resources so that you can easily maintain tests against them and manage their availablity well into the future.

Related posts:

Of all the stories that form the backbone of my life, there’s one that stands out to me more than any other, one that’s repeated out, time and time again since I was a child, with different people…

Poor villagers in the developing world are a distinctive, underserved microfinance segment. There are nearly a billion people who are illiterate in the world, and most live in villages or other rural…

The miracles that happen in life come in all shapes and sizes. Marathon training along the streets of New York City provided one example for writer Scott Harris.