And the API is…… launched🚀🚀
And along with it some beautifully crafted API documentation. In this post, we’ll present the highlights.
As a reminder mnai is leading the way in transforming unmanageable company datasets into meaningful data networks to uncover high-value insights. For instance, we have connected all UK companies, company officers and shareholders- a network of close to 100m relationships — to identify fraud and sales opportunities (among lots of other use cases).
In v1 we have intentionally kept the endpoints straight-forward with a plan to add more sophisticated insights later.
As well as some basic searches for UK companies and company officers:
Find UK company officers
Find UK companies
Find all officers for a UK company
We’ve published these endpoints to leverage the uniquely connected dimension of our data:
Expand a network starting with an officer
Expand a network starting with a company
Collect unlinked company officer records
First off, why an API?
Well, we exist to help data teams innovate and make an impact so we have to make things really easy for developers, data scientists, CDO’s and product managers to discover and start testing with our data. And when we say easy, it needs to be less than a couple of earth minutes.
An API coupled with a set of interactive docs is the smart way to go. With this approach — and by providing free API calls — users have everything they need to test within the documentation or to copy code snippets to their own tools.
After considering various options we opted to use the readme framework. We’re in good company as tech titans such as Cisco, Yelp, and Lyft also rely on readme to ensure a top-notch developer experience (#startuphack - their free tier provides everything you’ll need to get started).
In our case, readme syncs to our Open API 3.0 file which in turn is created dynamically out of our codebase using .net’s Swashbuckle. This ensures any changes to our API specifications are automatically reflected in the docs. Out of date docs are a 😱 screaming pain for devs.
API Documentation Spoiler Alert
Worse kept secret about API documentation? No one actually bothers reading much of it at all, they go straight to Quick Start or to the endpoints and use their intuition to start making calls.
Discovery to a successful call ✅ in <120 seconds?
Here is an example of an endpoint in our docs. Terse and to the point, all data entry is validated and any errors return solutions in the response.
JSON Shape & Content 🔧
With connected data, there is a particular challenge with how to shape the data response. In the case of our Expand a network starting with an officer endpoint it’s very easy to interpret in visual form:
But not so straightforward in JSON. We have nested the JSON response to replicate the outward steps of this network expansion: officer>company>officers>officer_appointment
Developer Support 🧯
The best APIs evolve from an engaged community of users and that is exactly what we are trying to nurture around our product. We exist to help data teams innovate and make an impact so will soon be adding a community section to our docs, allowing edit suggestions, and more. In the meantime email mike.oaten@mnai.tech or tweet to @connected_data_
Mike Oaten, Head of Connected Data, mnAI
