API Architecture for Mobile Usage

  Often when designing an API it can be a bit of a “make it up as you go along” or to just follow the same old patterns from the usual integration cook books.

However with access from external mobile devices you need to consider some extra things so here are a few  for you to consider …

The services that are exposed by the service Gateway will have the following characteristics:

• 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 request 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”.
• 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 simplify 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.  They must to be used as a surrogate for a session ID.
• ACID:
  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. This means that UIDs are indeed unique. For a relational database, this means that it must maintain referential integrity.
  • 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 the 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.

• Describable in WADL
  REST services are not able to be properly described in WSDL which is the de facto standard for service discovery.  When using REST and XML it is possible to describe the service in WSDL 2.0, however there are few examples that work well.  On the other hand WADL is not an agreed standard, and has not taken off in any great way.  In part this is because many of the APIs are in so called “Beta” state, in other words in a state of flux and so the formalisation in a Service Registry is not appropriate.  However given the use of the REST service for the B2B interface, and the general preference for a properly described service, it is proposed that Web Application Description Language (WADL) descriptions are created and made available.  For those REST services that are provided both XML and JSON then a WSDL 2.0 contract for the XML version of the API does make sense.  This will allow for the checking of the service against a defined template, useful for many purposes.