Benefits of a good API

Before going into the details I will give a bit of context. I'm currently working on a solution for a very specific and niche market. I focus is on the interaction with the users in the field that require a simple and effective solution, this is the area where the real value for the application is created. However there is also a requirement for an important, but less sexy, administrative bit of functionality. This functionality is pretty generic and available in standard commodity solutions. My aim it to integrate with one or more of these standard solutions and I spend some time to explore their various APIs.

The first thing I noticed is the huge variation in offered integration possibilities. This ranges from 'call us if you want to integrate' to offering a very clean, well documented and easy to use REST API. Let me describe how I short list the solutions I possibly want to integrate with.

  1. The solutions must cover a basic financial administration compliant with the legal requirements for the country I'm operating in.
  2. Is it a cloud, Software as a Service solution with a pay as you go business model, because that fits better in my total offering.
  3. Is there an API available without having to call and/or sign agreements and contracts. Since I don't have any customers (yet) the other party isn't interested in talking to me anyway.
  4. What kind of authentication is the API using? The consumer web has already learned us that basic username and password authentication is a no go. I take the same stand, because there are good ways to do it without me having to ask and store usernames and passwords. 
  5. What is the coverage of the API, is it only data exchange or does it also allow me to initiate and execute processes? A real world example could be: I collect the information for an invoice, send the invoice to your system, process the invoice to finalize it and retrieve the 'processed' invoice to present to my user. This all in real-time without a significant delay.
  6. Is the API stateless? This is a bit technical, but is important if you want to use the API from an environment where each API call can potentially come from a different server, something what is very likely to happen when using a cloud Platform as a Service environment.
  7. What is the interface used for the API, I find everything from exchanging files, SOAP web services to REST XML or JSON. The first is too limited, because it's usually to heavy for real-time integration and more suitable for batch integration and most of the time only covers data exchanges. SOAP web services are nice for enterprise integrations with an existing message bus system and a REST API has my top preference.
  8. What is the data format used in the API. The choice is usually between XML or JSON (Java script object notation) and it's not that important for me, but the preference is on JSON. JSON is lighter, easier to parse, requires less bandwidth (good for mobile solutions) and has better type checking. 

If you made it through the list your are a very likely candidate to become company I want to partner with. 

Unfortunately not many business solutions make it through the list and inn this respect the consumer web is already much more advanced than the business web. It's like in 'The importance of strategic user experience' with the challengers having the lead on the establishment and in the 'Old versus New World SaaS' the newer SaaS companies having the lead on the older SaaS companies. It's time that the establishment steps up and realizes that there is a huge long tail of opportunity up for grabs. 

A great API allows you to extend into niches beyond you can cover yourself without a significant extra effort. I'm more than willing, for my normal consultancy fees, to help you defining the future of your APIs.


Over a brown bag lunch at Startpad I asked for advice on architecting a Restful API that can  perform Actions for advanced business web apps. We concluded very few resources exist, no specific books, I was given a copy of RESTful Web Services (O'Reilly) by Richardson & Ruby.
In this respect its rather uncomfortable to realize huge gap between consumer and business web. I can begin to see a few architects such as @dotBen and @al3x cross over and help companies. The .NET architects seem to be MIA here.

Post a Comment