API First design mindset for effective mobile apps

Reading Time: 3 minutes

I recently finished a little free eBook from Mulesoft called “7 habits of Effective API and Service Management“. It’s a small read but it contains some good points that certainly help to set a good focus and mindset for creating small units of functionality in the form of services wrapped into a nice API. I won’t go into all the habits but the first habit is one that will help building a flexible and focussed API backend for your next mobile solution.

It’s about the so-called API-first design approach which basically means you want to begin with designing the API’s interface without implementing any actual functionality. Focus on the function specification; the naming, parameters and/or desired message body contents and the results that they should return.
After that start testing the interaction by building your app and interact with it.
When all feels clean and the functions operate like independent focussed interaction nodes you can finally build the actual functionality of the API and build stuff like backend integration with other systems – it be cloud or on-premise based.

So, in short the steps are:

  1. Design the API interface
  2. Test the API interface
  3. Build and implement the API’s underlying services

Although executing the first two steps can be done by setting up an API in code and returning mocked results (possibly giving back different results based on parameters or input when calling the API) I wanted to mention that there are some good tools around nowadays that let you define and test your API without actually code the stuff. And that means no setup of build environments, no code project creation and setup and all those little things that are certainly doable, but cost your quite some time while all you are interested in during the first two steps is definition and testing that your definition is working like you want.
One of those API design & testing tools – let me point you out that I’m not affiliated in any way – is Apiary.io. They let you setup a project within minutes and you can use an easy-to-learn definition format to type out the definition of your API and let it roll out as an API that is reacting like you designed and usable to test against. An actual implementation of the API definition that you typed out without writing a single line of actual code and no need to set up any coding project.

Besides using an API definition and testing tool that saves you time in a very early stage of your mobile solution project it actually makes independent app development more vivid. I often work on a mobile project as the first man in, quickly followed by a colleague building the API with functionality that I hand over using pseudo code definitions and/or an overview of the desired functions and responses.

Defining the interface in a common readable definition (Apiary also generates a sort of documentation portal which has interaction possibilities on the same page) with interaction possibilities also has the advantage that I can define and test against the API and any colleague can see actual function definitions and can interact and check out the desired responses for themselves.

This results in a no-nonsense fast way of designing your API, having it out there to interact with and test against in a snap AND communicating it with team members to have a parallel coding traject for both mobile client creation and backend development.

So, my advice is – whether you use an online API tool or not: create your API definition first and check what interface works the smoothest and supports the need of your clients the best and mold it in an interactive and agile process . Once you’ve settled on the communication style and interaction protocol the actual implementation will be created much easier and without all the common discussion fuzz. All of which in the end will crank up the quality and usability of your solution as a whole.