API design is a spicy topic! Many a wise word 1, 2, 3, 4 has been written about the best way to structure and version an API. In this article, we'll take a dip into the conflicting schools of API-design, establish a pragmatic middle-ground, and demonstrate how we can use Fly to bring our middle-ground to life.

Why API versioning? Well, when an API is made public, different client applications start using it. And as the business grows, the API also needs to grow and change without breaking existing client apps. Thus, API versioning was created. It helps us build new versions of our API’s, while keeping old ones intact. And although, this technique has become wildly popular amongst the development community, some controversy still exists on exactly how to do it.

While there is no agreed upon "right" way to design an API, it's helpful to identify and understand a few key areas that most developers do agree on. A well-structured web API should be...

1. An ongoing contract with the client. The contract guarantees consistency and stability; the client should be able to use the API without concern that it will suddenly break or vanish.

2. Backwards compatible after a change or upgrade. Old queries to new endpoints should still generate the expected return.

3. RESTful. It should speak the language of HTTP verbs: GET, PUT, POST, PATCH, DELETE, etc.

There are several common versioning methods that we can use to help us check all these boxes. Some of the most popular methods include header, URI and parameter versioning. Each method is justifiable and (when designed well) can render an excellent API. This example app uses what many believe is the most straightforward approach - URI versioning - a method that uses different paths for different versions of the API.

curl https://mightyapp.com/api/v1/lists/3

...

{
  "listId": "3",
  "shopping": "Shoes, tie, umbrella, snorkel",
  "leisure": "Skiing, surfing, snorkeling ",
  "food": "bananas, peanut butter, spinach",
  "cost": "One hundred dollars"
}

Ultimately, we want to be practical and ship things as quickly as we can. By plunking down the version number in the URI, the client can access /v1/ or /v2/ of the API. The URI version will change when your product fundamentally changes. It's readable, adaptable, and can plugin directly to a user's browser. This is the most common method currently used by APIs today. It allows users to explore different versions with just their browser and it’s super easy to use (for you and them)!

www.example.com/api/v1 --> points to version 1
www.example.com/api/v2 --> points to version 2
www.example.com/api/v3 --> points to version 3

and so on...  

Let's look at how we can do this easily with a Fly app.  

Most Fly Edge Apps are made up of multiple backends. For example, you can have a static-page on GitHub for your marketing page, a Kubernetes cluster or Heroku deployment for your application, and a database management system or two for your data. You can apply this same logic to your API design.  

When you build an API, you receive scalability and load balancing benefits by decoupling your API and hosting it as its own backend. API decoupling also gives us the opportunity to version with relative ease.  

Take a look at this example app we’ve created for you --> https://github.com/superfly/api-versioning  

2. Clone this repository and open it: git clone https://github.com/superfly/api-versioning.git, cd api-versioning

3. Start the Fly server: fly server

4. Head to http://localhost:3000/api/v0, http://localhost:3000/api/v1, and http://localhost:3000/api/v2 to see all the different versions of the API.  

When you sign up with Fly, you create your app by adding your hostname. Upon this hostname, you can attach all of your various backends and serve them all over HTTPS through a global network of intelligent load balancers. Each API endpoint is it's own backend, on it's own path, but all under one hostname!

The magic of this app lies within mounts. The “mount” function is useful for mounting different handlers onto different URL paths within your app.  

As the picture above demonstrates, this app operates several different API endpoints. Each endpoint is "mounted" onto a different path name. Where the goal of URI versioning is to use different paths for different versions of the API, this approach sure makes sense.

The backend endpoint is received by making a proxy fetch to the origin server. The response from each proxy fetch is mounted onto its own path.

Fly’s proxy library is useful for proxying requests to origins. You can use it to create fetch like functions for making requests to other backend services. In this case, we’ll be making requests to various API endpoints, then mounting the responses onto different paths.  

To add another API version, simply add another path and endpoint to the mount variable (index.js line#18-23). And voila! You have all your different API versions under one hostname, easily accessible to you and your users.  

We have endpoints that represent different versions of our API. Our users can receive a specific version by simply making a fetch request to the corresponding URL. If our application receives a major revision, we'll ceremonially bump our URI to the next version number.  

There are many different philosophies you can apply when designing and versioning your API. Using this example app, you can see how the flexible power of Fly URI backend routing can enable you to create the API architecture and versioning scheme of your wildest dreams.