“But it’s just an API!” cried my CEO when I estimated 2 months for a new API to be built. Problem is that we had had a very successful programme of exposing existing services as RESTful APIs, each taking a day or two… and because the buzzwords were the same, so was the expectation.
It’s easy to forget that an API is exactly that – an Interface… focusing on the contract, not the implementation details… And of course whilst it’s important to have a clear and precise interface to make it usable, it’s what goes on underneath that actually provides the value! Nobody benefits from easily consumable rubbish!
Communicating that is essential in setting expectations, and critical is understanding the variety of what APIs do. Some examples from the services I’ve built include:
- Passthru APIs – where all you are doing is changing the protocol to talk REST… the actual data is the same… possibly serialising the data into XML or JSON. These APIs have no need for persistence or business logic – they simply delegate to other services or systems.
- Transformation APIs – where you transform the data into a more consumable format- such as flattening address structures and applying naming rules.
- Context Map APIs – where you need to convert from one domain concept to another, often more than simply changing name from client to customer… perhaps things like aggregating orders to provide a customer summary.
- Process Wrapping APIs – where you have an asynchronous process lasting days or weeks which really isn’t what REST was designed to handle natively… so you need to generate “tickets” or “tokens”, store these and provide status query methods or register call-backs…
Then you have a whole host of non-functional requirements to consider: an API designed to handle 1000 transactions a second is vastly different from one that needs to only handle one a week… as is one when you are allowed only a maximum 10ms response time… and just being able to spin up another server on a cloud provider won’t help you if your API has an inherent bottleneck from a common resource.
So clearly not all APIs are the same… and they require different levels of architecting and design… but all of them benefit from appropriate governance… not to slow things down but to provide consistency in design, clear visibility throughout the organisation to avoid surprises… how many times has a “simple” API designed to be used internally gone viral and escaped into the public domain because it’s so useful? How many times does an API become “mission-critical” without the author knowing it? Once it’s “out there” it’s a pain to change…
I cannot imagine having to manage all this thorough a series of spreadsheets or Word documents… even diagrams from modelling tools quickly become out of date when there’s no need to update them. I’m happy to look at the code itself… that shows me what it does and what uses it within my currently open projects… but when I change a parameter – what is that going to impact? Follow a link to a design document? A programmer comment? I live in the real world…
So what do I do? Well you’d expect me to recommend Ignite wouldn’t you? Just remember it’s key to keep all that metadata about your services at the centre of your API development – avoid dead documents that nobody likes to maintain, as nobody will. How you choose to do that is up to you – but I think you’ll be hard put to find a better alternative than Ignite.