Living our Values: The “Meta API” at Koan

Published in

Hey Koan

5 min readSep 11, 2017

[Ahem…] Hello world?

Our mission at Koan is to help teams do their best work and we’re strong believers that documenting and living your values is a critical foundation to being a great team and company. So… it’s a fitting place to start our blog with a discussion of what we’re doing to live our own values.

At Koan, we’ve written an internal API that helps reinforce our company value of transparency. Here we’ll tell you a bit about what we built and why.

Our Values at Koan

One of our five core values is transparency:

Transparency
Our default is to share information because our best work is done with full context. Real feedback between one another is hard, but we do it anyway.

(The curious can find a full list of our values at the end of this post. Oh, and yes, we do in fact have associated animated gifs for each of our values… because why not?)

Access to information and data empowers us to do our jobs with autonomy, and that will become even more critical as the company grows. We also extend the transparency commitment to one another.

One simple litmus test: any data that we put into a Board of Directors deck should be accessible to everyone at the company. That’s things like our cash balance, spending info, and the Key Performance Indicators that we use as part of our quarterly goals.

This level of data sharing tends to be pretty easy at a small startup. It grows vulnerable as departmental silos set in, and as data controls become necessary (like for public companies). By formalizing data sharing via a central API at the very early stages of Koan, we’re aiming to head off these issues before they occur. We also hope to foster a positive information culture from the start where everyone feels empowered to answer the questions that they have.

The Meta API

We call our unified API for Koan “Meta”. A single, central API has several advantages:

Unified access control and permissions model — eliminates friction by not requiring different usernames and passwords for different data sets .
Easy ability to enforce robust security practices.
An opt-out vs. opt-in model for sharing data. All too often, things aren’t shared even if they can be.

Additionally, newer approaches like using a serverless architecture and the AWS API Gateway mean that a central API can be implemented without becoming a monolith. However, we’ll save technical details of how we implemented Meta for a separate post and focus here on what it does.

Meta is available as a set of REST endpoints. Though that’s handy for developers, we also want it to be easily accessible to every employee. We’ve therefore created a command-line helper that everyone gets setup with as part of on-boarding. For example, typing “meta” at the command-line yields the following:

$ meta
=============================================
Welcome to Meta, the API for Koan!Note: some commands have optional parameters.
You can type “meta /” to see full details
=============================================
company              basic company information
company/holidays     company holiday schedule
people               employee information
finance/cash         our current cash balance
finance/deathdate    when the company runs out of money
eng/repos            our Git repositories
eng/sprint           the current sprint number
eng/deploys          the currently deployed product versions
reports/completion   the user update completion data
reports/activeusers  the monthly active user data
reports/vanity       metrics that are interesting, but not important

Each Meta call returns JSON so that it’s easy to use the data in code, and several commands query external systems in real-time, such as the “finance/cash” request that connects to our accounting system.

A Semi-Practical Example

One thing that annoyed me regularly at my last company was how hard it became to order t-shirts for employees once we grew past the startup stage. There were always too many shirts of one size and not enough of another… So, meta includes t-shirt data from the start.

Let’s look at how we can use the meta to put together the perfect t-shirt order for the whole company. In this case, we’ll use the handy jq tool to manipulate the JSON returned by the “meta people” command:

$ meta people | jq '.value | .[] | .tshirt'
"M-L"
"M-S"
"M-L"
"M-M"
"M-L"

Now, not everyone is going to figure out how to parse data on the command-line. But the point is that with the data available, it becomes possible for anyone in the company to builds the tools they need and then share them with others. In fact, the Meta API already powers our company dashboard.

What’s Next

For now, the Meta API is a fun side project and handy time saver. We’re continuing to add new API calls as we need them and expect Meta’s power and utility to grow as Koan itself does. The dream is that someday Meta can represent a fully modern version of Amazon’s API Mandate.

Of course, building tooling to reinforce company values is also “meta” in that doing so is exactly our Koan product mission. Our belief is that values only mean something if they’re lived through behaviors, and that behaviors can be supported by great tools. We look forward to documenting the journey as we attempt to help your teams and companies do just that!

Koan’s Values

1. Transparency

Our default is to share information because our best work is done with full context. Real feedback between one another is hard, but we do it anyway.

2. Employees, Customers, the World. In that order.

We’re here to make a big impact. We start by creating a great environment for employees. That gives us the fuel to do amazing work for customers, which in turn earns us the opportunity to do better for the world.

3. Personal Accountability

Ownership and the ability to have great impact comes through earning it. Accountability in your role goes hand and hand with flexibility and trust in your role.