Building an API is like an orchestra: it takes a lot of instruments playing together and in-tune to get the right sound. If just one of those instruments is out of tune — or worse: missing completely — the end result is never quite what you had hoped for. Unfortunately, there’s no set guide on which instruments you need to build the perfect API, nor is there that one mythical arrangement that meets all needs.

What you need instead is a method that’ll guide you through the steps of building powerful APIs, with clear business orientation and developmental best practices in mind. APIOps® Cycles, says Marjukka Niinioja, is exactly that.

The Story of APIOps® Cycles

Marjukka recounts that several years ago, the Finnish government was somewhat worried about the state of their API economy. They had assessed the platform economy as one of two major technological advances in coming years, along with artificial intelligence, and they were two years behind Sweden in their progress.

What’s more, one of her clients had just realized the bigger, very connected picture of API development, coining the expression “All People are Important” in relation to APIs. The lesson here was that API development is difficult unless you engage specialists in all fields — marketing, customer experience, business development, integration, cloud infrastructure, and more.

The big realization came when Marjukka saw that the majority of API conferences, and equally API literature, were targeted towards a few select groups (notably: hardcore coders and product-focused business folk)… thus ignoring a holistic picture of API development that united the two factions.

Around this time, she had just helped Digia grow their API development infrastructure from consisting of just two teams to more than thirty — and yet when people started asking how, she didn’t know what to answer.

It was only when she was asked to train others that the eclectic APIOps® Cycles methodology was born, drawing from API business model canvases, value proposition canvases, technical and informational architectures, design guidelines, and more.

“It’s a method — it’s not just separate tools.”

Key Ideas in the APIOps® Cycles Approach

Prototyping is Essential

In API development, you want to hit the wall as fast as you can, says Marjukka. That means finding out about the problems an API is bound to face early on.

Instead of having the terrible realization that your API is not what you or your customers expected when you finally get to release date, take a page out of the APIOps® Cycles book: build a prototype or specification as soon as possible, and start discovering the inevitable before it’s too late.

Having a prototype will allow you to ask valuable questions like “is this what you expected?” and “should we continue?” It will help carry out API consumer interviews and inform API auditing from the start. And, as an added bonus: a specification gives consumers some leeway to figure out how they’re going to implement your API when it’s released.

What about API architecture, though? This can be a tough decision since purely agile projects have no time to lay out the perfect architecture in advance, says Marjukka. However, some architecture is definitely needed, and Marjukka suggests the little-known Minimum Viable API Architecture.

The goal of this prototyping phase is to do just enough development to get to a Minimum Viable Product, using mock-ups as much as possible and coding very little (if at all). Even if the end result of this prototyping stage is a very rough API — which needs recoding and reconfiguring — what’s important is that you get the interfaces in place and ensure the API is still aligned with its original business purpose.

DevOps Isn’t Sufficient

DevOps is the software development methodology linking software development itself with otherwise separate operations management… according to Marjukka: everyone swears by it.

Unfortunately, she believes DevOps is too simple a model for the world of APIs. In the API world, she sees two separate entities within “DevOps” simultaneously: the code that implements your API and the interface of your API. Oftentimes, these two have separate release cycles and need room to grow independently, and your approach to API development needs to stay conscious of that fact.

If you have any kind of API gateway, management system, or documentation portal, this becomes all the more relevant. Otherwise, you end with users getting an interface that has nothing to do with the reality of the API.

Security, Scalability, and Other NFRs

With an API, you have a handful of NFRs, or non-functional requirements, that describe operation at a level higher than just basic functionality. These include security, scalability, compliance, data requirements, and more.

Marjukka has noticed that in agile products, NFRs are ignored until code goes to production and something breaks. Naturally, this isn’t the right approach — it goes against our earlier principle of hitting the wall fast.

The solution? Make NFR documents look like coloring books, i.e. easy and business folk-friendly, instead of long and boring tomes which nobody knows how to fill out. Marjukka suggests you don’t spend a lot of time on all these NFRs (like localization, internationalization, network requirements, information architecture, and more), but that you do consider them.

Final Points

Marjukka acknowledges that previously many sales teams didn’t know what to do with an API — they were afraid to talk about them in front of customers (in case of any nasty technical questions), and functionality was difficult to describe. As a result, this led to lower adoption.

A quick-fix for this problem is to build your API from the inside-out, starting with a clear sense of the purpose of an API (including a basic business model and some core value proposition) that business folk can refer back to later. To this end, APIOps® Cycles includes tools like the business model and value proposition canvasses.

Finally, you need to understand how customers are going to discover your API, the presentation, and who is ultimately going to make the decision to use it. These factors are important even for internal APIs, but all the more so for public APIs.

As we’ve covered previously, another similar template is the API Model Canvas, a method inspired by the lean startup model that highlights the developer experience as a top priority.

The Takeaway

The API community has long needed a framework for great API practice, and perhaps APIOps® Cycles is exactly that. With a focus on early prototyping, building towards a clear purpose, and implementing just a few best practices, you might find this to be a priceless resource — best of all, it’s free!