3 ways to futureproof your backend API calls

November 13th, 2015

As soon as you put your app out into the wild, you can’t take it back, and your backend will have to support it going forward. While no release is perfect, wouldn’t it be nice to avoid issues before they happen? With a little bit of planning, you can. Here are three of my favorite ways to futureproof your API calls, and the best part is, they’re all very easy to implement.

1. Version your API

For your API, your URLs might look something like this:


But what happens when, a year down the line, you decide you want to completely change how your /users API works? You either have to completely break backwards compatibility, or change the URL to something that isn’t as nice as the one above. Instead, I’d recommend versioning your API from the beginning, like this:


Honestly, that’s all you need to do: update your routes so they include a “v1” in them. Your backend code doesn’t even need to change. Then, when you need to introduce a breaking feature to the API, you can leave your v1 code as is and create a new v2 URL with all the new stuff.

2. Use an API subdomain

If you’re just starting out, your backend might be living at the same place as your website, maybe http://yourapp.com. This is nice and simple, but it can leave you open to trouble down the road. What happens if you want to separate out your marketing site and your API? Existing versions of your apps are out in the wild, still calling http://yourapp.com, so it won’t be easy to change. What’s more, you can’t scale your API and site independently—if all of sudden, you get a large influx of users, it could potentially slow down your website until you ramp up new servers.

What I recommend is that you use an API subdomain from day 1, even if it points to the exact same servers as your root domain. In your app, when you make any API calls, make them to http://api.yourapp.com, rather than just http://yourapp.com. With only a few minutes of setting up a subdomain, you’ve now saved yourself lots of aggravation down the road.

3. Include your app’s version on every call

This one is so useful! Imagine you accidentally push out a version of your app where it’s expecting an integer response from your backend, but instead, your server is sending down a string (think "500" instead of 500). You somehow missed it in your testing, and now your app is crashing. You’d love to just change the server to start sending the right response, but that means now your older app versions will start crashing, so it’s a bit of a no-win situation.

But wait, what if your server knew what version of the app was calling the API and could adjust accordingly? If you plan ahead, it can.

One of the first things you should do when building out your API calls is to include your app’s current version. Even if you don’t need it at first, I guarantee your future self will be thanking you some day when you do. It’s simple too!

I like adding the app version as a header, maybe something like X-YOURAPP-VERSION. Here’s a quick example of how you’d add it in iOS (imagine you already have a request variable with your NSURLRequest):

NSString *appVersion = [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleShortVersionString"];
[request setValue:appVersion forHTTPHeaderField:@"X-YOURAPP-VERSION"];

Then, on the app server side, you can just do a simple check:

if request.headers['X-YOURAPP-VERSION'] == '1.4.5'
  score = user.score.to_i
  score = user.score.to_s

And just like that, you’ve saved the day.

Interested in working together?
Make Contact