Architectural strategies for an API consumed by mobile apps / browsers

Posted on January 16, 2013


If you are going to provide an API that will be consumed by Mobile devices (apps, browsers etc) then here are a few things to consider, mostly these are simply logical functional requirements.  It assumes that you are looking for an efficient API, that it will be accessed through a service gateway, and not directly from the provider platform, and that the data transitioning the interface is to be private.

  • Loosely couple the mobile application(s) from the back-end Business Service Functions.
    This means that the business functions do not necessarily need to have identical data structures and/or protocols.
  • Ensure that changes in the back-end service functions do not require an immediate and coordinated change in the clients.
    This means that each business service and the applications can be upgraded and modified on independent timescales.  This results in requirements to handle service routing, data and request transformations to support older versions of an API specification, among other things.
  • Ensure that the consumers of the API are authorised.
    The consumer may be a developer signing up and testing, or an application that is utilising the API,  all the requests must be authorised,  this means that they must also be authenticated.
  • Keep the API course grained.
    Because the connection between the device and the API is likely to be over a mobile internet radio link,  the performance of the link can vary greatly.  Therefore reducing the frequency of communication will normally result in a better user experience.  Also ensure that the design and execution of code does not make any assumptions about consistency of latency in a session,  consistency will be rare.
  • If you already have a B2B interface for this API then where feasible ensure that the client and the B2B interface functions are the same.
    However there are extra requirements that are necessary for a B2B interface for example the two parties normally need to mutually authenticate, and that the API actions should be strongly types and governed.  However where developers within enterprises are provided a choice between SOAP and REST interfaces the latter is overwhelmingly more popular, as long as the security requirements are met.
  • Create a Developer ecosystem that is self supporting as much as possible.
    The process that a developer follows to obtain access to the API should require the minimum human intervention by your staff.  This will reduce costs, and reduce the “getting started” time greatly.
  • Ensure that a developer can discover and obtain the API’s SDK, and start testing applications swiftly (minutes and hours, not days and weeks).
    As per above this is mainly by reducing or removing human involvement where possible.
  • API Gateway Extensibility which means that the API Service Gateway can be used for other APIs that may be launched.
    The Gateway should not have design elements that are dependent on the operational characteristics of this particular API (e.g. the authentication method, the logging method etc).
  • Provide the ability to convert between protocols so that the application can always use an HTTP based web service.
    As Business Services are connected to the API Gateway there will be a range of protocols used, such as JMS or similar messaging,  SOAP interfaces etc.  The Gateway must mediate and transform these protocols when practical.
  • Provide the ability to orchestrate the back end so that the application can make a single request even if this requires several calls to the business services to accomplish.
    This is the way to achieve course grained APIs and also to allow for changes over time as the API, the service consumers and the business services all evolve.
    and I’d consider using the “compensation” pattern to handle exceptions, because it is simple, extensible, and makes good use of orchestration.
  • Shared Service Contracts and descriptions where required.
    The suggested strategy is to put in place a Service Gateway that will provide the functions needed to allow for the separation between the back end systems (providers) and the consumers (applications and Business service systems through the B2B interface.)  This Service gateway is a standard approach and is a well known solution to this type of problem.

A select few of the non-functional requirements will include the following. Please note that there will be a large range of standard NFRs that would also need to be applied an catered for,  however these are the headline NFRs that should be considered (and I know they are very obvious,  but sometimes the obvious just has to be said!)

  • Scaleable:
    The platform as a whole should have no single point solutions – all services must be able to be scaled horizontally, by adding in an increasing number of servers to carry the load.  No system can be designed that requires a larger single system to scale (so called vertical scaling).  Any single point will become a single point of failure,  and therefore is a bad thing.  If you cannot avoid this then you must have contingency plans in place that delineate what to do when the failure occurs,  you do not want the sys admin to be working this out on the fly, after the failure has been discovered!
  • Robust:
    The platform should be able to deal with hardware and software failure.  Typically this means that the horizontal scaling is at least N+1,  where n is the number of machines required to deal with the expected traffic load and + 1 provides support for failure.  The sizing of N and indeed the 1 extra should be carried out when predicted service levels have been defined. Of course this assumes that you can design your service to be horizontally scalable.  If you are forced into some kind of “warm or cold spare” than again train your support staff to deal with the failover, and rehearse it on a regular basis.  Begin the process of eliminating this type of architecture in your system!
    The software should also allow for either sessions to be handled by several machines (eg clusters, or shared memory cache type approaches), or for all requests to be stateless so that any available server can handle the next request in a session.  So often sticky sessions in load balancers cause trouble, eg when you want to update a service.
  • High Performing
    The system should not increase service latencies in line with load,  therefore it must be designed to remove resource contentions generated across multiple simultaneous requests.  Further the latency should be predicable and consistent.  This is a big ask,  however if you are thinking you’ll be successful then it is worth baking this into the design early on.  A stitch in time, saves nine (hundred thousand!)


Posted in: Architecture, mobile