APIs Are Like a Box of Chocolates: Part 2

Posted by Steve Cormier

Find me on:

2/26/14 8:30 AM


In my last post I talked about APIs, whether they are really a new technology, and how to avoid being swept up in the hype surrounding them. In this post, I'll go over the important principles of software engineering and deployment that you should review if you plan on buying and implementing an API. 



Fundamentals Still Apply

It's very important to remember from a technical management perspective that the fundamentals of good system design are critical. 

Object Oriented PrinciplesThe collection of offered services should be built around object-oriented principles. This means a few things: 

  • Service-bundling should be cohesive around real-world entities representing a model, not a hodgepodge of what's needed for temporary functional purposes. 
  • Services should be built so they can allow discovery of interfaces, rather than requiring prior knowledge (tight-binding). 
  • Services should be able to be built upon each other (decomposability/inheritance) rather than base functionality being repeated and re-coded behind scenes, yielding an over-complicated and possibly inconsistent interface. 

Governance: Ease of use can be a double-edged sword, and the assurances of an API vendor might cause the technical manager to feel an unwarranted sense of security. The technical manager must be vigilant in terms of the following:

  • Security: the offering must have a robust security model, including role-based security. It should have been tested by friendly hacking. Consideration should be given to the resources of the company involved to thoroughly test changes introduced in new versions. Remember, you are exposing your company information to the world, and the same ease of access that lets external entities get information you want them to have can also allow hackers to get information that would ruin you. The use of JSON can introduce the possibility of code injection attacks that can bust your system wide open. 
  • Understandability: Let's say a particular service is offered in an API and it returns a new amount for something. People use this and get used to the data being returned. Now something gets changed, and the net amount calculation is different, though the service is still called the same. People start getting bad results. This is a classic example of a metadata governance failure to which services are not immune. Make sure that your system has a strategy for dealing with change that includes communication to your consumers and clear definitions of services. 
  • Consistency: One key to successful APIs, whether they are language (such as Java) or in a bundle of services, is consistency. This means that things don't suddenly disappear after consumers have become reliant on them and when a service's definitions change a new service is created rather than changing the existing one, followed by a deprecation period for the original service. 


APIs are not fundamentally new technology, but they are being bundled and marketed in a different way.  The positive aspect for a technical manager is that the offering company can be more easily held accountable for the product.  This can shift some development and governance activities (and the associated expense) away from the manager’s budget.  However, the buzz-wording and herd mentality that may lead to a rush to embrace API’s (and consequently pay too much for them) should be avoided.

Remember, the quality of the chocolates is not a matter of them coming in a box, or how pretty the box is. 






Topics: Optimization, Information Management, Information Integration, Digital Business Evolution