Friday, March 22, 2013

10 Tips for designing your mobile APIs

It's common for a mobile application to need to communicate with a web/cloud based service. At its simplest this will be just to retrieve data but it could also include sending data and user authorisation and management.
If you have to build the API that your application will use the following tips may be useful:

1. Version your API (from the very beginning)
At some point in the future the API will need to change. This may be to add, remove or change functionality. When this happens you may have to stop the use of part of the API or allow the consuming application to be clear about which behaviour, and type of response, it is expecting to be returned.
Your API is like a contract between your backend and the apps that use it. Without proper versioning you are risking the situation where one party can change the contract without the other even knowing. Having support for multiple versions of the API you can also continue to support users of your application who haven't been able to upgrade to the latest version of your app that uses the latest version of the app that knows all about the latest API changes.
Without versioning of the API you make it much easier to, inadvertently, stop applications working when changes are made to the API.

2. Don't return more data than you need to
The amount of data that is sent between the application and the server will, to some extent, impact the time it takes for the request to be made and the response to be received. Not only does this impact the amount of time a person spends staring at a loading animation, it may also impact the amount they spend on data charges.

3. Compress the data that is sent and received
In addition to not returning more data than is necessary, by compressing the data that is sent you can experience further benefits in speed and cost of data transfer.

4. Don't require unnecessary steps/requests
It's very common for APIs to be designed to provide separate discrete steps that reflect how the service is intended to be used. Quite often though, such discrete steps aren't the most efficient way of implementing a mobile application.
Let's take a simple example. Imagine the situation where a user has to log in (provide valid credentials) before being able to request data. It would be perfectly reasonable and understandable to think of this as two separate steps:
Step 1: The credentials are provided and, if valid, the API responds with a session token.
Step 2: The session token is passed when the request is made for the data.
That's probably unnecessary though. It would be much better if a single request could be made, passing credentials and the details of the data that is desired and, assuming valid credentials, both the data and a session token, for use in future requests, are returned.
The benefit of this is that fewer requests are faster and cheaper for the person using the app and may also (depending on how it's implemented) lead to simpler application code, which can lower development and support costs.
This may mean that you have to build the API to support both types of usage. This may lead to higher costs to support, document and maintain. But, if you're building your API just (or primarily) for your own use this may be more acceptable.

5. Combine requests (and responses)
In addition to multiple requests being made as part of an authentication or app start up process, it can also be common for multiple requests to be made to retrieve all the data for a single page or view in an application. Making a single request for all the data that a page requires, will be faster and cheaper than making multiple calls. Both factors that will be seen positively by the people using the application.
Again, this can also make the application code simpler. Especially with regard to handling the situations where multiple calls are made and not all of them are successful. If it becomes an all or nothing scenario the exception cases become much simpler.

6. Consider security from the beginning
Security is a massive and potentially complicated subject. This makes it particularly difficult to add on in a hurry in response to a security issue.
Remember to consider: securing data in transit; securing your data at rest; inappropriate or unauthorised use of the API; and potentially malicious or unexpected data having unintended consequences.

7. Plan and implement your caching policy carefully
If the data your API returns doesn't change very often be sure to implement appropriate caching strategies. This could involve keeping data in memory, rather than repeatedly reading it from disk. This should almost certainly involve the caching capabilities that are part of HTTP (assuming that that's the protocol you're communicating over).

If you do implement caching on your server, be sure to offer a way to forcibly invalidate it though.
Also make sure that you implement appropriate caching in the client application that consumes the API. You save time and resources if you can make a call and be told to keep using the data that was returned last time. You save more time and resources if you can avoid making that call in the first place.

8. Integrate analytics
Analytics are an essential part of understanding how an application is used. It's common for calls to an analytics service to be made in addition to the requests for data that are made during normal use of an app. For instance, if the app will attempt to call the server to refresh the displayed data on a page every time that the user navigates to that page then there is redundancy in adding a separate tracking/analytics call to track navigating to that page as well.
At its most primitive, the use of the API can serve as an indication of how and when the application is used. At the other end of the scale there are rich analytics tools and frameworks which can provide very detailed information about how users interact with the app. If you're somewhere in between then think carefully about how or if you're making additional/unnecessary calls purely for the purpose of tracking usage when you could get this from the calls made as part of the usage of the app.

9. Consider names carefully

The names you give the methods, objects, properties and parameters of your API will greatly impact the way those who are using the API understand it. It can be very tempting to use whatever terms or wording first come to mind when creating the API. As with all code though, the words you use play a great part in how the API is understood and expected to behave. Poorly named APIs can be a great source of confusion. Confusion leads to mistakes, mistakes lead to bugs, bugs lead to delays and support costs. Spend time on naming.

10. Don't forget your privacy policy and responsibilities
If you're capturing user data (and if you have logging on your server to record requests then you are) you need to have a privacy policy that details how you'll use the data. You'll also need to think about how you store and protect that data. Especially if it's personal and/or belongs or relates to children.

1 comment:

  1. For the louis vuitton replica woman who loves a different gift, Live, Laugh, Love is a abundant little allowance boutique with decor, accessories and apparel. Candles, handbags, jewelry, and shoes are just some of the abundant things they accept in stock. The agents is abreast and affable and are abiding to advice you acquisition the absolute Mother's Day gift.The alternative of alpha allowance sets and candles would accomplish the ideal allowance for Mothers Day. Mums can accede a moment in time to relax with a part of the the starting candles or actualize an affectionate amplitude for accepting enjoyed with admired ones. developed from sustainably sourced soy wax which minimizes smoke and melts abroad lengthier, there are 4 a array of scents to adjudge on from, all developed with 100% authentic important oils.Whether you are searching for a allowance for Mother's Day, charge to accord your kids a adumbration for a allowance for Mother's Day or need/want a shoe that can be beat just about everywhere. Every time I abrasion these, anyone says 'Hey, beautiful shoes!'. Handbags from Brandina the reliable are centered on bank top armchair fabrics to accommodate the absolutely feel apropos the Italian Riviers. the a lot of contempo blush and patterns apropos the bank top armchair actual could be the abstraction of Italian customized Marco Morosini. Morosini teamed with U.S. accompaniment Passport Brands, Inc. to yield the cast cast for the U.S. Brandina appear its U.S. commercial attack in affiliation application the accepted 53rd annual GRAMMY Awards amusement Lounge. Brandina is apropos the reliable adjustment of actuality apropos the 1950s Italian Riviera.Jewelries are consistently a accomplishment with commendations to Mother's day time gifts. jewellery Affairs design specialists and adept jewelers ensure that accessible barter could accept best top superior precious stones and service. The alone appearance accessible barter should do will be to gucci replica adjudge on out the best chaplet for that specific one, is not replica jewelry. Adornment is accepted to be a adequately accepted allowance for Mother's Day according to a customer intentions analysis conducted by the National Retail Federation (NRF) and BIGresearch. Of those shoppers planning to buy gifts, 31 percent intend to acquirement jewelry, which is 5 allotment credibility college than 2010.