People develop APIs for all sorts of reasons. They might be trying to create a tool to facilitate internal processes where they work, they could be building an external product for customers, or they might be building a third party tool designed to mash-up other services. And that’s really only scratching the surface of why someone might look to build an API, with some products encompassing parts or all of the above and more.

That’s why it’s difficult to come up with a repeatable blueprint for API development and business that is specific in terms of workflow and output; what’s right for one company won’t necessarily be right for another. That doesn’t mean, however, that there’s no value in trying to identify best practices relating to the production and maintenance of APIs.

Just as there are style guides for web API development (see API Handyman’s API Stylebook), in this article we’ll seek to determine if there are similarly repeatable guides for API economy involvement and business development.

A Manifesto For API Practice

The API Manifesto: “API economy boosting principles”

Assembling a group of principles is exactly what a group of Finnish developers have been doing over the past couple of years. The group oversees a working document called The API Manifesto; a doctrine of 7 economy boosting principles. We couldn’t help but notice that, when taken as a whole, the document looks an awful lot like a blueprint – albeit a non-technical one – for creating a successful API.

First introduced back in 2015, Jarkko Moilanen opened up a debate around the API economy in Finland. The aim was to find 5–10 theses or measures that would help to nurture the production of APIs within the country.

The working group is made of 18 contributors, including everyone from IT specialists to individuals who work(ed) in The Federation of Finnish Technology Industries and within the Ministry of Finance. In other words, a number of bright minds with strong opinions on the current and future direction of the API space.

Below, we’re going to look at each point in the manifesto and consider how it applies to API production in a broader sense.

Serve with digital interface (API)

This one is self-evident for our readers, but perhaps not yet readily apparent to some IT professionals. This statement is given particular emphasis within The API Manifesto:

“Functional interfaces are the precondition for the creation and scaling of digital ecosystems.”

It’s a bold statement, no doubt, but one that probably rings true for many of our readers. We’re not shy when it comes to writing about how API adoption is critical for present market advantage as well as future scalability. An API-first mindset is at the very core of developing microservices architectures and creating agile backends for digital platforms.

Prefer transparency

When some developers build something exciting, their first instinct is to hide it away until they can ensure it’s branded as theirs. Fortunately, ever since the birth of the open source movement and the explosive growth of knowledge sharing sites like Stack Overflow, open interfaces and public APIs are more and more common.

For example, when it comes to offering a public API and converting site visitors into customers, transparent status & uptime logs are recommended. And that’s with good reason; The API Manifesto highlights the fact that “transparency has been proven to produce better quality faster.” Of course, there are times when you’ll need to take certain measures to protect your IP. But, for most API developers, transparency is crucial in garnering sustained interest in a public API program.

Make onboarding as easy as possible

In case you haven’t gotten the message from this blog yet, solid documentation is extremely important. A welcoming developer portal that’s chock full of useful information isn’t just a “nice to have,” it’s essential for a powerful API.

The API Manifesto sums it up pretty neatly when it says “Good documentation is also rich in case studies and code examples.” We can’t say it much clearer than that!

Measure, get feedback, and iterate

For way too many developers, putting an API live is the final step in the project. The rest of us know that a v1 release is just the first step of an ongoing process. Monitoring high traffic API endpoints can help you not only to determine whether or not the API is a success, but also offer valuable insight into which areas you should focus on next.

The topic of versioning can be a divisive one, but having an approach for iterative change is reccomended within The API Manifesto: “Feedback allows iteration, which means continuous development of the interface with the smallest and the most easily manageable steps. Implement interface versioning if necessary.”

It’s worth remembering that the manifesto is designed to offer guidance, rather than set things in stone. Whether or not you retire APIs and replace them with new versions or, as Roy Fielding suggests, don’t version your API at all, will likely depend on the size and frequency of changes you’re planning to make.

Collaborate with others

Most APIs have collaboration at their core. Whether that means working with developer users to establish what they need from an API, or working with partners to ensure that your APIs are compatible with one another, it’s always easier to ask and answer questions than having to test everything manually.

Granted, it isn’t always possible to work like this. If you’re trying to plug your API into Google data, for example, it’s pretty unlikely that you’ll be able to speak to someone at the company. Still, it’s wise to keep collaboration at the core of what you do as much as possible: “Vibrant and diverse ecosystems are built around excellent interfaces.”

Implement consistently

When viewers consider API usage, they can easily be turned off by status pages that haven’t recently been updated, or inconsistent API styling.

When it comes to the technical nitty gritty, standardization and keeping to a consistent schedule may not always be possible. The API Manifesto reminds us of the fact that “extensive multi-hundred-page requirement specifications are usually already outdated when completed.” Thus, incremental, continuous updating is surely a more agile approach to maintain consistency.

But that doesn’t mean that you can’t standardize the way APIs are described; “regardless of who implements them or what technology is used…Use the same design patterns, but also leave room for maneuvering and adjusting.”

Build for purpose

This may be the last point in The API Manifesto, but it’s arguably the most important point for any API producer to adhere to.“Build it and they will come” isn’t a valid API marketing strategy, but also “build it and they will stay” isn’t either.

An API needs to have ongoing attention in addition to a useful purpose at its core. This value proposition might equate to saving the user time, performing novel functionality, or generating cool user experiences. Without that, it will lack the stickiness that all good products need to retain and grow a user base.

Final Thoughts

The API Manifesto may not get into a lot of the technicalities of building an API — such as comparing REST vs SOAP vs GraphQL vs RPC, or whether to go public or sell access etc. — but it still makes for interesting reading for anyone looking at improving the API space.

What’s perhaps most interesting about The API Manifesto is, despite the wide range of public and private sector individuals behind it, just how consistent and congruous each of the points made within it is.

There may never be a silver bullet for exactly how to create the perfect API, but anyone trying to get a feel for the basic principles behind most types of API development could do a lot worse than to start with a document like The API Manifesto.