Mobile API Design

08/01/2017 by Andrew Cowart

Mobile devices have certain limitations to account for that you may not need to think about when designing an API on normal websites. Think about the features of the device and consider the issues that the developers that will interact with your API might face. Will there ever be a time when it cannot reach the API? What sort of storage and computational specs does the device have? What standard knowledge would you expect the developer using your API to know?

Use lightweight responses

Web APIs normally send responses in JSON or XML format, which the mobile device then parses out and stores locally as objects. When designing a mobile API, you'll want to make sure these responses are "lightweight." This means sending only the information that is about to be displayed on the screen instead of sending back additional data that the client may not yet need (or even ever need).

  • Just the basics

    As an example, when a user logs in to a social network, the server will send back a response containing the most recent news. The user is only going to see the first 5-10 stories on a page and maybe a few comments for each news story. Instead of the response sending back all of the stories with all of the comments, we recommend the response send back only the first few news items, with only one or two comments visible on each. Additional requests for more information should be sent as the user requests them.

    Another example can be found in music applications. If the mobile device only shows you a list of genres after you log in, the API response should generally only contain a list of genres. Once the user clicks into a genre, only then it should further request and show a list of stations or songs in that genre. This way, the mobile client doesn’t waste data and processing power on information that the user isn’t even interested in.

  • Infinite scrolling

    One way of minimizing the amount of information returned in API requests can be accomplished on mobile by using "infinite scrolling" pages -- where items are broken up into pages, but the pages aren't delimited as such in the app. Instead, once the user scrolls to the end of a page, the application will send a new request to the API and request more items automatically.

 

Account for intermittent connectivity

When designing for an API that will be used on a desktop, you don’t have to worry about your user losing connectivity multiple times in a session. They are either connected or they aren’t. With technology going mobile, people are coming to expect access to either wifi or a cellular network wherever they go. As much as we want to be connected 24-7 anywhere in the world, the reality is that we just aren’t there yet. When designing APIs for mobile devices, you need to prepare for intermittent connectivity.

  • Response Handling

    Signal loss is going to happen. Designing your API to expect and account for it is the best thing you can do. When no connectivity is detected, we suggest allowing for queueing of responses while offline. Then, if appropriate, send them when the connection returns or bundle the changes into one request that gets sent the next time the device comes online.

  • Push Notifications

    Losing connectivity doesn’t just mean you can’t send information, it also means you can’t receive it. By default, both Apple and Google will try to re-send pushes for a month before giving up and deciding they can't deliver them. When sending out push notifications, you should be aware that your users may not receive them in a timely fashion. The best thing you can do is use the features included in push notifications to your advantage.

    For example, an old notification can be replaced with a more recent version. From a practical standpoint, this would be useful if your app had a messaging service and the user gets a message. You'd want to send them a push that says, "You've got a message." -- but if they get another message and you know they haven't logged on to read their original message, you can replace the original with a new one that says, "You've got two messages."  This ensures that when the user does finally get the push, it has the latest information.

  • Acknowledge Receipt

    Mobile API developers should be aware that there are many cases where a device may be unreachable for periods of time and develop accordingly. One system to work around this is to make sure that devices send an acknowledgement back to the server when they receive the data successfully. Until the client sends that acknowledgement, the server sends the data over and over using an exponential backoff retry method.

    In such a system, the server does its best to send the data without overloading itself by scheduling the retries at continually longer and longer intervals. Once the client acknowledges receipt of the push, the server can then stop retrying.

  • I was right in the middle of…

    Losing connectivity can happen at the worst times, such as when your API is in the middle of a multi-step process. Instead of scrapping everything when a loss of connectivity occurs, account for the client sending a state that may not match exactly what the server expects.  Work with the client developer to cover what should happen during a loss of connection during multi-part processes. 

 

Use REST standards where possible

 

REST is a set of standards that is popular amongst developers and guides web transactions. It is the most popular set of standards used in building APIs today. There are a couple of key aspects that make REST work particularly well for mobile.

  • Stateless

    It should be stateless. The client should pass all of the information required in a request without the server having to keep track of the client's previous requests. This is beneficial since mobile clients can be a mix of offline/online states, and the server may not always have all of the information about the client's state available to it.

  • Cacheable

    It should be cacheable. A good example for this would be a social network news feed. If you make a request to the server, it returns all of the latest news. Later on, if the client sends the same request ("What's the latest news?"), it can include a header that states the last time it received news. For example, "What's the latest news? The last news I received was at 3:00." The server can then reply with, "That's the latest news", and the client can just use the existing cached data.

    This interaction is built into most existing mobile network libraries, which assists in saving bandwidth/processing. Having these libraries available also makes it easier to develop mobile apps. Because of these options, Metova recommends against using non-standard response codes or other deviations from normal REST practices.

  • Account for mobile battery drain

    Some people feel the same way about their cell battery as they do about time; you can never have enough and it goes by too fast. Software that puts a strain on battery usage is the scourge of the stores. Mishandling data, whether it’s for geolocation or app updates, is one way to push your user’s battery to the limit.

  • Data Handling

    Minimize the amount of polling your API uses. Allow users to manually refresh their data so energy is spent when information is actively requested. Where possible, push data to users instead of spending energy having them poll every x minutes or hours. Use cache controls. If users already have the latest data, don’t waste bandwidth by downloading and parsing it again.

 

When designing your API, keep the device that will be using it in mind. If your mobile API is difficult to manage or puts extra strain on a device, developers won’t want to use it and your users won’t like how their apps perform. Design your mobile APIs to be lightweight, account for inevitable connectivity loss and battery drain, and use REST standards when possible.  

Andrew Cowart
VP of Technology, Metova