10 Tips for designing your mobile APIs

It's common for a mobile application to need to communicate with a web/cloud based service. At its simplest this will be just to retrieve data but it could also include sending data and user authorisation and management.
If you have to build the API that your application will use the following tips may be useful:

1. Version your API (from the very beginning)
At some point in the future the API will need to change. This may be to add, remove or change functionality. When this happens you may have to stop the use of part of the API or allow the consuming application to be clear about which behaviour, and type of response, it is expecting to be returned.
Your API is like a contract between your backend and the apps that use it. Without proper versioning you are risking the situation where one party can change the contract without the other even knowing. Having support for multiple versions of the API you can also continue to support users of your application who haven't been able to upgrade to the latest version of your app that uses the latest version of the app that knows all about the latest API changes.
Without versioning of the API you make it much easier to, inadvertently, stop applications working when changes are made to the API.

2. Don't return more data than you need to
The amount of data that is sent between the application and the server will, to some extent, impact the time it takes for the request to be made and the response to be received. Not only does this impact the amount of time a person spends staring at a loading animation, it may also impact the amount they spend on data charges.

3. Compress the data that is sent and received
In addition to not returning more data than is necessary, by compressing the data that is sent you can experience further benefits in speed and cost of data transfer.

4. Don't require unnecessary steps/requests
It's very common for APIs to be designed to provide separate discrete steps that reflect how the service is intended to be used. Quite often though, such discrete steps aren't the most efficient way of implementing a mobile application.
Let's take a simple example. Imagine the situation where a user has to log in (provide valid credentials) before being able to request data. It would be perfectly reasonable and understandable to think of this as two separate steps:
Step 1: The credentials are provided and, if valid, the API responds with a session token.
Step 2: The session token is passed when the request is made for the data.
That's probably unnecessary though. It would be much better if a single request could be made, passing credentials and the details of the data that is desired and, assuming valid credentials, both the data and a session token, for use in future requests, are returned.
The benefit of this is that fewer requests are faster and cheaper for the person using the app and may also (depending on how it's implemented) lead to simpler application code, which can lower development and support costs.
This may mean that you have to build the API to support both types of usage. This may lead to higher costs to support, document and maintain. But, if you're building your API just (or primarily) for your own use this may be more acceptable.

5. Combine requests (and responses)
In addition to multiple requests being made as part of an authentication or app start up process, it can also be common for multiple requests to be made to retrieve all the data for a single page or view in an application. Making a single request for all the data that a page requires, will be faster and cheaper than making multiple calls. Both factors that will be seen positively by the people using the application.
Again, this can also make the application code simpler. Especially with regard to handling the situations where multiple calls are made and not all of them are successful. If it becomes an all or nothing scenario the exception cases become much simpler.

6. Consider security from the beginning
Security is a massive and potentially complicated subject. This makes it particularly difficult to add on in a hurry in response to a security issue.
Remember to consider: securing data in transit; securing your data at rest; inappropriate or unauthorised use of the API; and potentially malicious or unexpected data having unintended consequences.

7. Plan and implement your caching policy carefully
If the data your API returns doesn't change very often be sure to implement appropriate caching strategies. This could involve keeping data in memory, rather than repeatedly reading it from disk. This should almost certainly involve the caching capabilities that are part of HTTP (assuming that that's the protocol you're communicating over).


If you do implement caching on your server, be sure to offer a way to forcibly invalidate it though.
Also make sure that you implement appropriate caching in the client application that consumes the API. You save time and resources if you can make a call and be told to keep using the data that was returned last time. You save more time and resources if you can avoid making that call in the first place.


8. Integrate analytics
Analytics are an essential part of understanding how an application is used. It's common for calls to an analytics service to be made in addition to the requests for data that are made during normal use of an app. For instance, if the app will attempt to call the server to refresh the displayed data on a page every time that the user navigates to that page then there is redundancy in adding a separate tracking/analytics call to track navigating to that page as well.
At its most primitive, the use of the API can serve as an indication of how and when the application is used. At the other end of the scale there are rich analytics tools and frameworks which can provide very detailed information about how users interact with the app. If you're somewhere in between then think carefully about how or if you're making additional/unnecessary calls purely for the purpose of tracking usage when you could get this from the calls made as part of the usage of the app.

9. Consider names carefully

The names you give the methods, objects, properties and parameters of your API will greatly impact the way those who are using the API understand it. It can be very tempting to use whatever terms or wording first come to mind when creating the API. As with all code though, the words you use play a great part in how the API is understood and expected to behave. Poorly named APIs can be a great source of confusion. Confusion leads to mistakes, mistakes lead to bugs, bugs lead to delays and support costs. Spend time on naming.

10. Don't forget your privacy policy and responsibilities
If you're capturing user data (and if you have logging on your server to record requests then you are) you need to have a privacy policy that details how you'll use the data. You'll also need to think about how you store and protect that data. Especially if it's personal and/or belongs or relates to children.