API Platform : a reference Architecture, including mobile APIs

APIs have become an important part of business’ strategy, and it’s product mix.

So what are they and why should I care

Well firstly they are a way to provide software services to selected partners, or the whole world,  as you see fit.

Typically each API performs a single action (give the details of this parcel, tell me the exchange rate, add this person to the database, etc etc,)

AIs have been around for a very long time,  but now we are seeing that organisations, are making them products in their own right, with various pricing models ranging from free, through tiered prices based on usage to subscription, and combinations of the three.

So as an architect what would I expect to see in a platform to provide APIs.

For a small company, with a few APIs then you could just use your web infrastrcuture to manage it.

However I am considering the picture where you have several APIs, in groups, that you want to be able to supply and charge for.

You’d like developers to be able to register (on board) and select the services they require, and to be able to invite partners as well.

The APIs will need to be on a different production cycle to the in house services that provide them,  so degree of loose coupling and message routing will be needed.  This is even more important when you start to have 3rdparty developers on board,  because their development cycle will not be in lock step with yours and therefore you need to be able to make changes without necessarily affecting them, eg if you upgrade a service to a newer version with different API calls.

I’d like to suggest that the APIs should be product managed and therefore for the system to provide decent reporting, both at the product level, and at the operational level.  Of all the complaints I’ve heard from the large number of product managers I’ve worked with,  a lack of reporting on product performance is always the loudest and longest.

Lastly we may want to have a fraud / risk engine to review how the APIs are being used to ensure that nothing dodgy is happening (in particular if money is involved.

The trick then is to have a dual system approach for the gateway,  and then separate out the other functions.

The dual system for the gateway, at first sight seems a bit like over kill,  however it is wise to not have any business logic in the service gateway that actually exposes your APIs to the world,  and in having a separate integration service behind it allows for a great deal of control, meaning that you have options when service updates, upgrades, revisions etc come along.

OK so here is the picture,  this bears in mind all of the above.

Lets talk about what’s in there, and what’s not.

• API Developer Portal
  The system that the developer uses to discover services, sign up for them, and sign off too.  This site also has to proide teh downloads, the examples, the documents that support the APIs.  The developer will (sweeping generalisation coming up) will be lazy, you need to hold their hand and provide everything they need to get going quickly and efficiently,  and furthermore to find help when they need it.
  Thus you will want to have forums where issues and questions can be raised and answered.
  You also want to have a “blog / wiki” type service to provide the talk about the future.
  Don’t forget that the developer will want to have reports on their consumption of services, trends on usage, costs and invoicing etc to manage their relationship with you.
• API Service Gateway
  This is the box that actually provides the services to the developers and their users.  The apps / systems using the API connect to this box,  therefore it is your front line. Choose it well and make sure it is properly safe,  it will come under attack.  This is why there is no business logic in this layer, you have to assume that it could be compromised.  It is the box that controls Access and Authentication.  It may use an internal service to provide data (eg an LDAP server) but the decision should be made here. Keep this box simple.  the less it does, the better it can be protected.  Consider an appliance, these tend to be better as service exposure gateways.  I have not included methods for dealing with Denial of Service (DOS) or Distributed DOS (that is huge volumes of traffic) as I think these should form part of your general security infrastructure.
  I have shown three port types as follows: –
• • Web
    Consumed (architect talk for used) by PCs and servers, often these are fully functional and can be data heavy.  Also near real time type services can be though here.
  • Mobile
    Often very similar to the web APIs except with lighter weight protocols (eg JSON rather than XML, REST rather than SOAP etc).
    why separate these from the “web” set,  well you may have to perform a different set of authentication actions, you may need to have some special protocol actions etc.
    When considering mobile APIs it is wise to make the API calls synchronous (for ease) and stateless.  This means that the API will cope better with “mobile conditions” where the link may be flakey, or that the device changes it’s IP address, and even access network (eg switches from Wifi to 3G) between consecutive calls.
    It it likely that you will also need to consider that the data being sent over mobile may need to be re-encoded (for example from XML to JSON) and this should not be performed, if at all possible, in the “Mobile” adaptors for the API.
  • B2B
    Special interfaces for business partners,  typically this is server to server interface, and may well use a different authentication method (again) including use of VPNs and greater use of certificates.  Also some functions may only be visible to partners, and this is a useful way of ensuring they are out of the way of the other developers (policy enforcement aside)
• Integration to Providers
  Providers is architect speak for the systems that actually execute the API service call.
  It is in this service that you perform any decisions, routing, major data or protocol conversions.  This keeps all this safely out of the way of the Service Gateway.  In this way these actions are safer, and more able to be controlled and managed operationally.
  This split also means that we can make sure that the best solution for this important action,  and being a realist, it also also for the provision of this function at a later date.  It may be that an existing service bus is the best platform for this,  and that could be true.  Be sure that it is able to be flexible enough to cope with the rate of change of the API platform, especially when providers are upgraded.
• Operational Control and Analytics
  With a platform that is in use by external parties, many of whom will have an SLA with you in place it is wise to have a defined operational support node that will ensure that the systems are running smoothly, predicting issues (eg raising traffic) and generally protecting your reputation.
  I have included an analytics node here because it is wise to be keeping data on how the system is operating, what the usage is, and to be able to report on this.  For example if there is money involved this could form the stream of data into the Revenue Assurance function (if you have one).  If the API product is new, then you need reporting,  this is often left out to save money or time,  however without reliable good quality reporting it can be very difficult to make decisions,  so reporting is a key ingredient to an agile, rapid turn around product set.
• API Service Management
  The API product will have quite a few aspects that will need managing, such as the SLAs, pricing, releasing functions etc.  Further the users of the API will have to be managed, eg authorising an upgrade in permissions, off boarding abusers and so on.  Therefore there is need for a system to allow this to be done.  May be the same as the developer platform, if this is the case, make sure you are very strict in the separation of concerns in the code, and have a strong Authentication method for identifying the internal staff.
• Billing and reporting:
  If you charge for use of the API,  or even pay people to use it,  then you’ll need a billing system to generate the bills.  This system must also be able to switch off accounts that are in contention (eg arrears). Financial reporting will be key as well (of course). Don’t forget your developers and partners will want financial reports too.
• [optional] Risk / threat profiler
  This is a system that watches the use of the platform and will trigger alerts when it decides that actions are outsides of the boundary of the normal usage.  Eg a system hitting the system to frequently.  Perhaps a set of calls setting then reversing changes etc.  This really comes in to its own for financial services, and for those with strict IPR or similar (eg full traceability on document flows in Pharma, aerospace and the like)

Those systems that are required but not a part of the platform

• Service Providers <<atomic>>
  These are the back end systems that do the work,  and provide the service that is being offered as an API.
  I have put them as <<atomic>> the funny angle brackets mean this is a key word if you will, and the Atomic is architecture speak for meaning that the API does what it does in a single call,  and does not require you to compose a range of calls.  Eg give me a price for product X.
  why are they here,  well a lot of the APIs that you expose to the world will be derivatives of these services.
  It may be that they use a different protocol to that exposed on the API Service Gateway,  in which case you’ll need to direct the call through a protocol adapter, ideally NOT performed on the API Service Gateway.
• Service Bus <<composite>>
  I used the term Service Bus, but it could be a range of integration middle-ware.  The point is that you are bale to call a composition engine that will organise those times when it is necessary to make several service calls to answer a request, for example asking for account details, may require calls to authentication, to financials, and to product catalogues or some such mix of services.
  So the important thing here is that this is the existing integration middleware, and that the API platform sits separately to it.  This seperation is important when loose coupling is required.
  Lastly it should be pointed out that the atomic services mentioned above may well be accessed through this existing middleware platform,  and so my showing them separately on the diagram does not mean they must be accessed directly.
• Sandbox Test Services
  This is the exception that proves the rule,  whilst many folks will be thinking that it is optional,  developers can test their own stuff for them selves.  However the truth is you need to provide developers with the ability to test their systems against yours,  and you do not want this hitting the back end of your systems.  For when security it paramount, or for when reliability and uptime of the service are the most important, then you may even provide a separate Service Gateway instance so that the test traffic is separated from the main platform.  I have not depicted this in the diagram.
• Other users of the system
  I have not included the other users the sys admins fin operations, those running reports, or performing upgrades and other maintenance, finance, security, auditors and the like.
  From the  users point of view there are likely to be several sets of different types of user.
  There will be a range of developer types from unregistered folks, through “open” developers, to business partners, and in the end many graduations in between,  all needing different profiles controlling their access and rights in the platform.