App APIs — 10 key things developers must know

At ArcTouch, we spend a lot of time thinking about user experience (UX) design and how to create engaging and lovable apps. Our designers obsess about every detail, from the overall customer journey to the size and color of user interface elements, to delight people at every opportunity.

But there’s an often-overlooked component that can make or break any app experience: the interface to the data and internal business systems that power the app. Usually, this is stored on a server (the back end), and app APIs (Application Programming Interface) allow the app (the front end) to access the information on that server.

App APIs or app islands?

Very few apps exist today without a back end. An app without a back end is an island and will quickly become stale and limited. Most apps have one or more back-end services they tie into, either from third parties (such as payment gateways or image processing) to legacy systems (like an internal HR system) or new functionality specific to the app.

Our iOS developers and Android developers specialize in building complex apps that integrate with a variety of back ends and often build the app APIs that provide access to these. An API’s performance can have a dramatic effect on the user experience. When an API is done right, the user won’t even notice. When app APIs go wrong, apps may stall or crash — prompting bad experiences, negative reviews, and dreaded uninstalls. An API could very well be the reason a user loves or hates your application.

Planning for your API should start on Day 1 of your project because the decisions you make when starting a new mobile application project define its success. So, when it comes to developing a great mobile app API, where do you start? In this blog post, we will explain ten key things developers must know when developing an app API.

1. Don’t reinvent the (RESTful API) architecture

One of the most used architecture styles for APIs is RESTful (Representational State Transfer). REST APIs use HTTP requests to perform the actions GET, POST, PUT, PATCH and DELETE. REST APIs are ideal for app APIs since they are lightweight and easy to implement, and there are a lot of development and testing tools to take advantage of.

2. Choose explanatory API URL endpoints

Design clear API URL endpoints for the development team to understand what that resource contains. For example, if your API is for the beverage industry, then some of your resources might be a beer, a brand, and a user. So, you could construct your API endpoints like:

GET → /beers
POST → /beers
GET → /beers/{beerId}
PUT → /beers/{beerId}
PATCH → /beers/{beerId}
DELETE → /beers/{beerId}
GET → /beers/{beerId}/brand
GET → /users/{userId}
GET → /users/{userId}/favoriteBeers

Note the pattern and how obvious it is to developers what that resource contains. Each HTTP verb describes the action that the endpoint will perform. It’s very important to keep a pattern — otherwise it would be very difficult to organize the endpoints.

Now take a look at these (bad) endpoints:

/getBeers
/createNewBeer
/addBeerToFavorite
/addNewUser
/returnBeer/{beerId}

At first, these endpoints seem clear. However, APIs using those endpoints will frustrate developers because each will need new endpoints for every possible action. It will become increasingly difficult and confusing to create a new endpoint.

3. Version your app APIs

When there are several different versions of an app out in the market, servers need to consolidate and handle the various requests coming in from new and legacy users alike. Mobile developers don’t always have the luxury of forcing software updates for all users, so an API needs to handle requests from different app versions. The endpoints would look like this:

GET → /v1/beers
GET → /v2/beers

4. Assign heavy lifting to the server

The computing resources available on a mobile device are limited. Meanwhile, the computational power in the back-end is much more robust, especially on massive server farms provided by Microsoft Azure and Amazon AWS. So some operations, even if they can be done on the client side, are much better suited for the back end.

In addition, the back end is very close to where your data is stored, while your mobile application can be anywhere on the planet. Processing and querying data server-side is much faster — rather than the client making multiple API calls to fetch the data.

5. Prioritize performance and scalability

When app APIs take a long time to respond to a request, the user will be waiting for that action to be completed — which can be very frustrating. So, measuring and considering the response time of each endpoint is essential.

Even if your app APIs are responding at the right time during individual testing, you need to factor in the possibility that thousands or even millions of users may be using it on a given day. Several architectures and technologies can help you achieve scalability — including microservices, serverless architecture, autoscaling services, and even orchestrators like Kubernetes or Docker Swarm.

6. Use standard security protocols and user authentication

Any requests that travel through the Internet will pass through routers and public servers. Most of them are trustworthy, but some may be compromised. In that case, responses can be altered, and sensitive data like credit card numbers or passwords may be captured. To protect your application against such cases, use standard encryption technologies and authentication protocols already tested by the industry. HTTPS is a must-have in the back end. Data traffic over HTTP is very easy to capture or even change. When your app isn’t protected, your information is exposed to the world.

If your app API supports user authentication, use standard protocols such as OAUTH or OPENID. They are used by companies including Microsoft, Google, Amazon or Facebook — and have proven to be safe. Apple now offers its Sign In with Apple for iOS devices.  Additionally, eliminating the need for users to have to create a unique account for your app reduces friction when they first launch it.

7. Use three back-end environments

During the lifecycle of an application, it goes through various updates — each with development, testing, and production phases. Each phase has a different version of the software, and each has a different purpose. While a new feature is being developed, another one may be in testing, and many others may be in production. During the app lifecycle, it is imperative that one phase of development doesn’t interfere with the other. To ensure this, we always follow commercial-quality software development best practices and use three environments for the back end: development, staging, and production. We have a process to migrate from one to the other and also to roll back if there’s a critical issue.

8. Let the data determine the database

When architecting your back end, there are two main database technologies you can choose from: a relational database or a document database. Relational databases allow for more standardized data, with predefined schemas and advanced capabilities for querying data. One of the major disadvantages of this type of database is that when data is updated, tables are locked until the transaction is completed — which makes scaling your application more difficult.

Document databases are usually more flexible, as data is stored in documents that can be as complex as you need. These documents can be upgraded freely without blocking actions, making this type of database more easily scalable and distributed globally.

There are also cloud document databases — they work in the same way as traditional document databases, but are managed by cloud providers. With a few clicks, you can scale and distribute the data globally. This type of database is preferred for serverless applications.

9. API responses should be clear

When creating API responses, be clear and consistent. Use standard HTTP status codes — 200, 202 and 204 for success responses and 4XX for errors. Do not mix “camelCase”, “snake_case” or “PascalCase” for the JSON keys. Use whatever formatting you prefer, but use it consistently.

Be careful with dates and times. Accept and send all dates in the ISO 8601 format with UTC values. The server shouldn’t pick the time zone, or even how the date should be displayed. The mobile app client should decide how to display it, based on the device settings for region and language. Remember, your audience could be anywhere around the globe.

10. API responses should be efficient

At some point in the future, you might have a lot of user data stored in your back-end database. So, when making calls to the API, there may be a lot of results to return — and the computational costs associated with retrieving, transferring, and consuming that data are high. And your app will become less and less responsive as you add more users. This isn’t good!

To fix this, you’ll need to paginate the results. App developers can use a range of methods for API filtering, sorting, and pagination. Choose one — and remember to be consistent.

Need help with your app APIs?

ArcTouch has been designing and building apps from the ground up since the dawn of the app store. If you need advice on structuring your back-end APIs and web services, contact us for a free consultation.