Most Mobile Projects Fail at the API: How to Minimize Risk

APIs (application programming interfaces) make mobile apps and browser apps work. A great API serves as the building block for all the other components of a successful mobile app. Whether app developers are creating their own API or piggybacking off a larger system, a successful API will lead to a better working, more timely mobile app.

While creating a consistent and timely API is not the flashiest or the most visible part of a new mobile app, it is arguably one of the most important aspects of any well-developed app.

Here are a few aspects of a strong API strategy that leads to productive mobile development:

APIs should be planned strategically for the long-term stability.

Before the API development can start, as much as possible of the requirements needs to be known and the developers themselves need to have a strong understanding of the problem they are solving. That usually means that developers need to dive deep into the problem domain and get very specific answers about everything that’s unclear.

Once the development team has a good understanding of the problem, it’s time to design the system. Most APIs need a way to store data and for most use cases, relational databases are a great way to store data.

The way data is stored can have a big impact on the performance and functionality of the API so it’s very important to invest an appropriate amount of time into defining the database entities and relationships between them.

This is a great investment of time because it ensures you build the system on a solid foundation.

If API design is not done properly before development starts, massive changes might be required later on in the project and the costs are considerably larger at that point. Any change on the API may cause changes on all of the clients using it.

Good API design follows standard conventions which are appropriate for the problem the API solves. By following standards, the API is more intuitive to mobile developers and therefore creates a certain ease of use.

By following standards in API development, app developers can use existing knowledge and tools – making app development less costly. Having logical naming and consistency throughout the API goes a long way to minimize development costs for users of the API.

A typical modern API is a RESTful API which uses JSON as the data transfer format. For some use cases, standards like gRPC, Thrift and GraphQL are more appropriate.

As much as is possible, the API should behave predictably and work without (unpleasant) surprises.

That includes using a consistent format of error responses and the appropriate HTTP status codes.

API tests are as important as app testing, in that API tests ensure that applications, systems, databases, and networks can communicate with each other and exchange information. Testing should both prove the API is working as expected (i.e., without bugs) and according to its specifications.

As much as is possible, testing of the API should be automated by using a continuous integration setup.

Testing should focus on use cases which are as close as possible to those that are or will be happening in production.

In order to make integration of mobile apps with the API easier, there should always be one or more test environments. Test environments are API deployments to separate endpoints which allow for various testing which can’t and shouldn’t be done in production. In fact, testing in production should be avoided altogether if at all possible.

If the production API is already live, a good way to get representative test data into the test environments is simply copying the data over from production periodically. When doing this it’s very important to remove all personal information like names, email addresses, bank account numbers since the test environments don’t imply the same level of data security and same access rules.

By ensuring the test environments work in the exact same way as the production environment, integration with production for the mobile teams should be much easier. Switching to using the production APIs should be as simple as changing the host name from test.example.com to example.com.

For the API to work consistently (and to troubleshoot any later problems), API developers should document everything. The documentation should be clear, correct, and easy to understand. The documentation should also be updated as the API changes so it doesn’t contain outdated and incorrect information.

While API documentation is very important, it’s often regarded as tedious and boring work by developers so it’s important to make the documentation process as easy and automated as possible. The API documentation should be automatically deployed with the API, without any manual intervention needed. We can take this a step further and eliminate a lot of the manual work by generating documentation with examples from API test cases using tools like our own dox.

Business requirements change over time, the supporting software also needs to change to keep solving the right problems. When the API changes, we want the API clients to keep working.

Since non-breaking changes, like just adding new functionality to an API, are usually not a problem — let’s focus on the breaking changes. How do we handle those?

The naive solution would be to immediately update all the API clients, but that isn’t as simple with mobile apps. iOS apps need to undergo a review process by Apple which can take days, sometimes even weeks. Even after the mobile app updates end up in the respective app stores, many users won’t update soon (or ever) to a newer version of the app.

The main tool for solving this problem is API versioning. The most straightforward way to use API versioning is to copy all the functionality of the API and start serving the new version of the API on different endpoints, including the breaking changes. Usually the new endpoints are just prefixed with a different version, so the API would support calls to both /api/v1/login and /api/v2/login — with the old endpoint retaining the old behavior.

While API versioning is a powerful tool, sometimes it isn’t enough. Maintaining multiple versions of an API can be time consuming, and thus costly. Sometimes, for various reasons, API versioning may not even be possible. It’s wise to design a mechanism which can force clients to update to a newer version. For mobile apps we use Prince of Versions to specify a minimum client version per platform.

While this mechanism should rarely be used, when you truly need it — it’s invaluable. You can use it not only for breaking API changes, but for any situation when you may need to force the client to update.

To handle breaking changes on the API you can either deploy a new version of the API which increases the maintenance burden or force all the clients to update which is intrusive to users of mobile apps.

Choose wisely.

To minimize the risk for mobile projects, when building APIs you should:

APIs are the foundation upon which modern mobile and web apps are built. They’re not easy to plan and build, and the decisions you make whilst building them will come back to reward (or haunt) you for years to come.

So choose wisely and enjoy the challenge.