API: the spine of your app

Making mobile apps is awesome (i love it, and even wrote a post about its beauty) and it takes all kinds of aspects that you need to get lined up.

But most mobile apps aren’t selfcontained
, especially the business apps that I work on at my day job at Valid. In fact, they usually need to interact with other applications – company backend systems – if you will or need centralized storage that can be connected to from anywhere.

The high volume small timed interactions that are so common for mobile applications and the specific goal and functionality that define an app made them premier cancidates for creating and using a clean API that will act as it’s middleman is very important.

In this post i’ll share you some tips and resources that will help you understand what a good API is all about and more..

What makes for a good API?

There are a couple of rules of thumb that will define an API as “good” when it is:

  • an interface that provides for, and takes what is necessary for your functionality
  • conforming to web standards
  • secure in the way it communicates with your app
  • generic enough to support different clients (apps, websites, etc) but specific enough for the logic behind it
  • easy to use and self-explanatory (reading an api url should make sense!)

Also, you need to think ahead when building an API and make a decision if the API is solely for yourself or if – by any chance – you’ll be sharing it with 3th party developers in the future. The latter means that you need to think about a key providing mechanism that identifies the utilizing party (which is small-time impact develop wise) and may indicate that the robustness of the API – among which scalability, load handling, uptime, … – needs to be ready for the higher usage- and interaction rate.

Clouds will make you happy

Maybe you’re like scalability, load handling, uptime, what?? Luckily nowadays you don’t really need to worry about that stuff. Cloud platforms all over have been emerging in this mobile era and there are quite some available that not only provide a hosting service for your API, they have generic API definition and data storage solutions ready for you to setup and use!
They are called MbaaS and make it very easy to focus on your apps and the functionality that define them instead of the infrastructure and plumbing that are needed to setup a central data solution.MBaaS

Some of the MbaaS platforms even have connectors (plugins, if you will) that couple your API (defined on their platform) to services like Sendgrid and alike.
The true advantage of using MbaaS is that you can quickly define your API and storage (some even create tables dynamically when you’re uploading objects) setup and start interacting with them within the hour.

And what is the flipside of this beautiful coin, you might ask? There are very good MbaaS platforms that will let you build and use their platform for free up to a certain usage threshold. This permits you to build commercial apps and let them gain users. But when you reach the threshold, you need to get a paid plan for a fixed price that will suit your need or else they’ll let you pay for each call or Mb of data that passes the limit.

That makes it worthwhile to compare the platforms not only by feature but also by cost. Making a comparison sheet for various scenario’s (for when you’re app will gain 10.000, 100.000 or 1 M users) and check what will be your best fit.

Check out this link to see some MbaaS platforms that are out there. One that i’ve worked with mostly isn’t there though; Microsoft’s Windows Azure platform alongside with their Mobile Services  make a very stable and robuust platform that even has auto scaling functionality on board!

Defining a proper API to interact with

There are various big companies that have public API’s at their disposal;  Facebook, FourSquare, Twitter, etc, etc.. They all setup nice API’s that are used by thousands and thousands of people and they all look great. But they also have small differences in their setup.

Some differences that can be seen when looking closely at the API’s:

  • some indicate API versioning in their URL’s, others use header information
  • one api uses .json at the end of a call to indicate the return format, others give it along in the request
  • differences in how they use plurals and verbs differently to indicate resource

 

All these things may strike you as finesses of the implementation but they actually are quite important. Especially when your API will be a hit and many people will start to use them using all sorts of different types of clients.

Here are some good resources on how to develop a good API for your app. 
 DO mind though, there is NO holy grail and no ONE correct path for developing an API. Read the resources and get yourself familiarized but let factors like your product’s characteristics , developer team preferences and the target audience of the API make your own decisions on how to actually implement the API’s interface:

  • Rest API Design Rulebook [http://shop.oreilly.com/product/0636920021575.do] A nice book that is mostly interesting because it explains why you should (or shouldn’t) create the API url structure in a certain way. Don’t sit to long on the WRML for too long, since it isn’t used much and – although it has its charms – it will be overkill for the most of us
  • Best practices for a pragmatic Restful API [http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#json-requests] A nice blog post with some good pointers on implementing a Restful API
  • Apiary.IO API tool [http://apiary.io] This tool is very interesting especially if you’re collaborating with others on creating a good API. By defining an API with their syntax you’ll end up with documentation for your API, a blueprint if you will. It even functions as a Mockup endpoint that you can interact with to see if the API is what you want it to be! Very nice to start your API implementation with
  • Teach a dog to REST [https://blog.apigee.com/detail/restful_api_design] A nice blog post about the concept of ReST; for most purposes this is THE protocol for a usable and easy API

 

Concluding all the information given in this post; the time that your backend (or middleware, depending on your architecture) was just a little basket to drop information in have passes. This is the time where you need a stable, easy-to-use and well defined interface that isn’t client or platform specific. It needs to be able to be used by more than a mobile app to be versatile and future proof and keep your service standing tall: the spine of your app.