Characteristics for Mobile API Services

Posted on October 10, 2013


For the last few years APIs have become more and more important for business, often they become either a source of revenue, or central to success when use by third parties is the key driver.  However when making APIs for mobile it is necessary to consider some characteristics that will make the difference between success and at best mediocrity or failure.
In years gone by SOAP and similar control mechanisms were used to manage and define API services,  however this type of system is not suitable for mobile use,  and indeed, for many B2B systems.  
So here are my tips for a mobile API,  not claiming anything new,  just a bringing together in one place.
  • Idempotent:
    This means that the service can be called multiple times, and the result will always be the same.  Thus if a service calls a payment API twice with the same request, only a single payment should be made.  This is a vital characteristic because the clients are connected over mobile networks which can be unreliable and have great variances in throughput and latency.  This can result in a client issuing a request twice (or more), believing the initial request to have been “lost”.
    Or indeed the app may have been interrupted, and so on restart re-creates the messages it was sending.
  • Stateless:
    The services should not require a state to be maintained between the client and the service. Stateless services are better for scaling, for redundancy and simplifying the exchange of data between the client and server.  This does not mean that a Correlation ID is not desirable,  and Correlation IDs should be established however this must to be used as a surrogate for a session.
    Maintaining state is expensive, it requires a setup and teardown, and generally results in extra data being exchanged to maintain this state.  Further it often ties a client to a particular server or cluster thereof,  however mobiles have the habot of switching from wifi to cellular, or having long delays between successive requests. (Or for example the user takes a phone call, which may stop the app from running for the duration of the phone call.
    Thus if you can design around a formally maintained session then do it.
  • ACID:
    No I am not taking you back to the sixties …
    In short this means that the service always returns even when success is not possible.  The components of ACID are: –

    • Atomic – Enables changes to be grouped and performed as if they’re a single operation–all or nothing.
    • Consistent – A transaction begins and ends with valid data, even if the data is invalid during the transaction. For example this means that UIDs are indeed unique. For a relational database, this means that it must maintain referential integrity. If the API is called with valid data then the effect/outcome is always the same.
    • Isolated – Each transaction executes as if it’s the only one; it is independent of any other concurrent transactions. A transaction’s intermediate state is not visible to operations outside of the transaction.
    • Durable – Changes made by the transaction are persisted and cannot be lost, even if the resource subsequently fails.

Making the service idempotent, ACID and Stateless typically reduces the “chatter” in the API because the error and exception handling is simplified, the requests, if properly RESTful will minimise the number of resources exchanged between the client and the services. A well designed API that follows these rules will be simpler to understand compared to action orientated SOAP type interfaces.  Further with the unreliability of a mobile network as the link layer, this also reduces the likelihood of incomplete actions due to network outage issues.

Posted in: Architecture, mobile