At Steamclock, we often build mobile apps for web-savvy tech companies. Luckily for us, these kinds of clients often already have solid APIs available for us to build on top of, letting us hit the ground running.

Most of the time, anyhow. In our experience, how long it takes to build a mobile app can vary a lot depending on API backends’ quality, consistency, and level of support. In extreme cases, an app being built on an excellent supporting API could take half as much work to get to a given level of user experience than something built on top of a rough and unpredictable backend.

While we’ve built up experience working around the foibles of real-world APIs, we’ve also been building experience estimating how many foibles a given API may have.

Based on that experience, we’ve built a general checklist to use during estimation – and also to share with clients – that helps gauge how straightforward an API is going to be to build on top of, and identify what kind of backend investments could speed up app development and reduce maintenance costs.

While this checklist is a high-level review and doesn’t capture all the nuance that makes a given API straightforward or complex to work with, it should provide a good start for teams considering the state of their APIs, and help estimate how much work will be needed to tame a given backend and build a great app on top of it.

We hope this is helpful with your next project – best of luck!

The Steamclock API Checklist

Structure and Consistency

One of the most useful things an API backend can do is follow standards where possible, and be internally consistent elsewhere.

1. Does the API consistently return JSON with clearly separated data, or are there some endpoints or errors that return XML, HTML, or other formats?
2. Is the API consistent in structure and naming, such that similar data coming back from different endpoints have consistent names and data formats?
3. Does the API consistently use HTTP methods and status codes, or are there edge cases where a “success” status code may have an error payload, or certain codes or methods are being used for novel purposes?
4. Is the API versioned, such that if return payloads change in the future, existing apps in the field can still work with the old API for a grace period?
5. Are there supplementary 3rd-party APIs that the app will need to use for certain kinds of data? If so, these same questions will apply to them.

Development and Deployment

Building a good mobile app will almost always require some improvements to the API. How we support iteration on the backend will play a big part in success, especially in terms of how long it takes to make progress.

1. Have these APIs already been “battle tested” by a production product?
2. How much bandwidth do you have in terms of API developer resources to make fixes, make improvements, and answer questions about these APIs?
3. How familiar is your existing software team with how these APIs are built and maintained?
4. What facilities do you have for testing using staging, demo, and other kinds of test data?
5. How consistent is your staging environment and production?
6. How quickly can you roll a fix or change into your staging environment, and then on to production?

Functionality and Performance

Since answering functionality questions depends a lot on app scope, one of the first things we do when evaluating a project is start roughing out wireframes for key screens. Once we have that, we can audit the APIs for what they do and don’t provide.

1. Is it possible to get all the data we need to display in-app from the current API endpoints?
2. Does getting the data for any particular screen take a number of simultaneous or, worse, serial requests that will result in a slow user experience?
3. Are there endpoints that return ambiguous data, for example returning a 0 that sometimes means $0.00 and sometimes means “no value”?
4. Are there endpoints that return “raw” data that needs complicated transformations before being displayed (e.g. filtered and combined somehow) that would be better calculated on the API side?
5. Are there important API endpoints that return very slowly and may require UX mitigation?
6. What facilities do the APIs have for letting the app specify transformations such as filtering, sorting, paging, and so on? A sophisticated interface like GraphQL is great, but even consistent sorting and pagination parameters go a long way.

Authentication

A lot of fairly RESTful APIs that are consumed by web apps have idiosyncratic or under-documented authentication mechanisms. Since authentication expectations are quite different between websites and mobile apps, this area is always worth evaluating early on.

1. Does the API support modern token-based authentication, or does it assume clients are web browsers that set and manage cookies?
2. Are the rules for session expiry and session renewal clearly documented and understood?
3. Does the API currently provide provisions for extra security considerations like answering security questions or two factor authentication?
4. Do the API responses clearly distinguish between different authentication exceptions such as incorrect password, session expired and needs renewal, account locked out, security question incorrect, etc.?

Documentation

While we can work together to help fill out documentation where needed, getting developers already familiar with the API to build out and update docs can be a big early win for app development projects.

1. What percentage of the API endpoints are currently documented?
2. Does the endpoint documentation include example requests and payloads?
3. Are the supported options listed for fields where “enum” style values are expected?
4. Is the documentation in a format where we can reasonably collaborate to make corrections and fill gaps? (e.g. a wiki or other web-based CMS)
5. Does the documentation include information on error states and edge cases, or is it focused on the “happy path”?