Deep Tech: APIs are interfaces. Interfaces are Code.

Blog Post created by Jay_Thorne Employee on Mar 5, 2018

In the beginning, there was code. Very shortly thereafter there was the first bug, followed by the first bug report and the first merge conflict. I’d like to claim that while many things have radically changed since Babbage like languages and components and tools, the risks and the issues haven’t.  Right now, the tools of choice nearly always involve APIs and we sometimes forget that the interfaces are code as well. 


Any product that provides business value has some level of business logic. Since APIs have become the de facto standard linking systems large and small together, making the overall integration dependent on at least the interfaces, the interfaces need to be treated with the same discipline that code does.


Version control: If you’re a one-person software development team, and it’s 2018, chances are fairly good that you use a local version control system for your code, just because. At two people on the team, you’d be crazy to not have a version control system. At ten people on a team running without a local git, or subversion or something is like driving to work in rush hour traffic in a car with no brakes. It can be done, but it’s excruciatingly risky. You would have to be going very slowly. Version control systems give you velocity. APIs evolve, just like code does, so if you want to have API velocity, you need version control.


Modern deployment in the Enterprise needs huge attention to Version Control. As a developer, working on your own, concentrating closely on the task at hand, you need a build / test / rebuild / retest cycle measured in seconds at most. Coffee breaks for a compile are a thing of the past.


That cycle time has a range: At the opposite end of the pipeline, when you deploy a line of business application to a Fortune 500 company’s externally facing data product, you mostly don’t just “try something and test it in production”, you would want to have 100% repeatability, and you want to be able to reverse changes as easily as you put them in. Failed upgrades happen, they can’t be allowed to kill your business.


This implies that the mechanics of an API’s lifecycle needs to be a full development lifecycle. The current accepted practice is a combination of version control, build tooling that is automated, and deployment that is also automated.


Are you prepared for rolling back your next API interface update? Microservices imply that you have smaller deployed components – but now you have more interfaces. That means version discipline becomes a bigger part of your success.


Interfaces, Contracts: In more specific terms, an API can be a type of interface definition. Some of the metadata formats, especially in swagger 3.0, interface and contract are expressed. SOAP and Early REST was almost contract-free, but the industry is starting to embrace contracts.


When you change the back-end system, there’s a high chance that the interface contract changes. It would be useful to mentally disconnect the contract and interface and expect to have both in the version control system. While the interfaces are far more on the Dev side, the contract is on the Ops side. That implies that the same kinds of effect that DevOps has had on code deployment has been felt in API deployments: automation, repeatability, build tools, and version control are now the best practice.


If you’re going to provide any value in an API, Microservices or even ancient SOAP based systems, the interfaces, contracts & metadata need the same level of discipline you already use on your code itself. The alternative is either madness or stasis; either cowboy culture in dev and Ops, or no changes at all.


Many thanks to Geoff Anderson for much input on this article.