Writing good APIs for Mobile Apps
The path to best User and Developer Experience
A large part of the building a good App relies on having good APIs in the first place. APIs are helping Apps with providing great features, but if they aren’t well designed they can cause mediocre user experience. In this article I will go through what I believe is essential to build good APIs.
As a AndroidDev or iOSDev you can use this as your manifesto to start the conversation your API teammates.
The characteristics of a good API
I should first define what is a good API. Below is my humble opinion forged with 15+ years in both Mobile development and API development, learning from successes and failures. I hope you will be able to leverage some of my experience.
State of the art APIs should be a combination of the below attributes:
- fast
- reliable
- return the right data
- secure
- designed for the consumers
- versioned
- documented
- error handled
- flexible and powerful
Diving into it
The scene is set, now let’s have a look at each and every points above and understand how can this be implemented and why it is important.
⚡️ Speed
An API should be fast, and by fast I mean it should return within 100ms on a wifi network connected to high speed Internet. This number include both the processing time in the infrastructure as well as the transport time through the network. This number can sometimes be hard to achieve for very complexe features, but at least we should work toward this goal. This often mean optimising code, queries and infrastructure. The cloud offering provides all the necessary tools to balance and scale so that the APIs remain fast. In addition some mechanism like gzip can help reduce the transport time when returning large amount of data. 100ms is perceivable but expected by the users, after 1 second user wonder if the action was registered and after 5 seconds they usually consider leaving the experience.
Return the right data
An API should return the correct data and the right amount of data, this can help with speed too. Returning correct data mean enough for the app to do its job but no more. For listing, this mean implementing a proper paging mechanism for instance. Preventing to return too many nested objects (unless required). Having sufficient parameters so that developers can adjust settings to get exactly what they need (see flexibility below).
Reliable
Reliability and consistency are essential, so the experience remain the same no matter the load or the new functionality. The first pet is an infrastructure job, making sure that the platform can absorb the load and remain available at all time. The second one is about test coverage so that no regression can be introduced.
In order to maintain this I would recommend to put in place proper monitoring and CI/CD.
🔒 Secure
APIs should be build with security in mind, using the encrypted connection and secrets. HTTPS should always be used, letsencrypt and others offer free https certificates so they are no excuse anymore.
The API access should require an API Key, so that it is possible to identify the client app and revoke if required, OAuth can be used for that with PassportJS and OAuth2orize.
On top of that, the APIs/gateway should implement some sort of token like JWT
Finally, I would recommend to implement scopes, so that a user have access to only a subset of APIs.
Understand who is using the API
Knowing that Apps will connect to the API might help on deciding contracts. API developers usually think in term of micro services, but often on apps, features requires multiple micro services to achieve the tasks. It can be smart to use BFF (Backend for Frontend), so that complex orchestration is done once, on backend side and the API returns the right data in one go, preventing multiple back and forth.
Underneath, the the BFF will use multiple micro services, but given this work will be done in the infrastructure, the latency will be much less, allowing a faster response time. More over, by doing this on the backend, we prevent the mobile team to implement complex orchestration, for each platform, Android, iOS, Web. Saving time and money and improving the consistency across all platforms.
Versioning
APIs are changing, they evolve just like any software, and from time to time they can introduce breaking changes. This is why it is crucial to have a versioning system in place. I’m not talking about Git here, but a proper version naming X.y.z. When the contract change, the version should change too.
This will prevent to break the apps because the API has changed, in addition it will facilitate migration from one version to another as well as testing.
📄 Updated documentation
Documentation and contracts are essential for a good communication between the teams, they must remain up-to-date, ideally using a technology of documentation auto generated, like Swagger-autogen for NodeJS.
That will allow the mobile team to get started on the implementation even if the API is not stable. Any change in the API contract should lead to a new version of that API, so that it is easy for any team member to understand what update is required.
⚠️ Error handling
Properly handling error will prevent unexpected behaviour or strange messaging to the end user. The errors should be meaningful and designed to be understood by the API consumer (ie: the apps). Both HTTP error codes and business error code should be used. The first one will help to deal with the general handling, while the second will help dealing with a particular business scenario. With the business code, an error message in plain English should be returned. This will help the developers to understand straight away what is wrong.
Finally the error codes should be documented.
Flexible and powerful
The API should be simple to use, but powerful enough, by offering extra parameters to allow complex use cases.
This way general use cases can be implemented easily without restraining complexe upcoming scenarios. For instance you might have a default number of item per page, but allow overriding it with a parameter. Offering extra filtering options for a search such as dates, last X item as well as ordering options.
Conclusion
This is the ideal world, where API are built with customer in mind, I’m sure you might have to compromise here and there, but hopefully this can be your target state. I hope Mobile and API developers alike will agree on this, so we can build beautiful apps together for our users.
If you have anything to add, I would love to hear about it! What works best for you and your team?
