I’m a product management guy so requirements get me all excited. I’m also an API guy, so when we put together APIs and requirements, well then, I’m in hog heaven. That said I do want to try and make sure that we’re all on the same page when it comes to understanding how APIs can help and hinder with meeting the various different types of requirements we need to consider.
In software we tend to think of requirements as falling into one of two categories; functional (“what” the system does), and non-functional (“how well” the system does it).
|Correctness||Ability with which the software respects the specification|
|Performance||Ease with which the software is doing the work it is supposed to do. Usually measured as response-time or throughput|
|Reliability||Ability with which the software performs its required functions under stated conditions for a specified period of time|
|Robustness||Ability with which the software copes with errors during execution|
|Scalability||Ability with which the software handles growing amounts of work in a graceful manner|
|Security||Degree to which the software protects against threats|
|Usability||Ease with which the software can be used by specific users to achieve specific goals|
Table above duplicated from an excellent presentation on meeting NFRs in Agile Development from Mario Cardinal.
I think APIs actually introduce a third class of implementation specific requirements (“the way” the system does it).
There are lots of examples of this, but let’s just take a look at a couple of security specifics for SOAP and REST.
|User Authentication||WS-Security Supporting Token||OAuth|
|Data privacy||WS-Security Message Encryption||HTTPS|
|App Authentication||WS-Security Message Signature||HMAC Header Signature or OAuth|
It’s probably not a completely accurate way to think of it, because really the implementation specific requirements are the way in which we have to meet functional or non-functional requirements for a particular API implementation. Right now I hope you’re looking back at that last sentence and are saying to yourself, “but in that case, an implementation-specific requirement is just either an FR, or an NFR.” This is really the key ah-ha moment in all of this. There is a big difference between an API and an API implementation; in fact a single API could have lots of implementations.
Even more important than the idea of implementation specific requirements (which I’ll abbreviate as ISRs from now) is the question of whether an API addresses functional requirements, or whether the functional requirements are really addressed by the system that exposes the API?
It’s one thing if you happen to be Facebook or Twitter, and have a platform that was built with exposing an API in mind, or was even built using an API first mindset. But in most enterprises that won’t be the case. You will have a whole bunch of different enterprise applications, all of which deliver some valuable capabilities, but what you need to do is deliver real business value to your partners and customers by delivering an API that uses functionality from many of these applications. In this case most of your functional requirements will be met by the applications themselves, with your service or API platform tweaking a few things in the process of delivering the API. What you need to focus on is how you can ensure that your API will meet its functional and implementation specific requirements. In many cases your API platform will be responsible for creating the various different implementations, see my earlier posts on the anatomy of an API Gateway, API Orchestration, and API Proxy or Gateway. In this case you need to ensure that your API Platform can not only enforce security and QoS policies, but can also take multiple backed services of different types and create a consistent API interface that it can expose as SOAP, REST/XML, REST/JSON, WebSockets, AMQP, and whatever the industry will throw at you next.