What Skills Do Your APIs Offer?

Much has been written about API design techniques – from choosing the right HTTP verb to guidance on response code usage and hypermedia dos and don’ts. We get caught up in the technical details of what our API should look like under the covers, while ignoring the humans that the APIs were designed to help.

We need to remember that APIs exist to help complete a job-to-be-done. Either the job requires the use of the API to start and finish the work, it requires the API for some portion of the work, or the job is to bridge systems and organizations through machine-to-machine communication.

So, how do your API endpoints participate in these jobs? Even better, how do you explain the capabilities of your API endpoints to those less familiar with the technical details of HTTP, GET, and POST? It is time to start communicating about our APIs in a new way. One that supports the human side of APIs. It is time to start talking about our API endpoints as skills.

What skills do your APIs offer?

If I were to look at your API documentation – from your reference documentation in Swagger (now OpenAPI) to your getting started guides – what would I see? Would I see a bunch of content centered around your POSTs, GETs, PUTs, and DELETEs? Or, would I see the skills your API offers to get stuff done?

The worst offenders I have seen are API reference docs that like this:

GET /organizations
Description: Get all organizations

No kidding? The GET /organizations endpoint gets a list of all organizations?! Why do we allow ourselves to document our APIs this way? Instead of “Get all organizations”, we need to look for a better ways to communicate and share our API’s skills with our product team, our company, and our developer ecosystem.

Meeting people where they are

What skills do your APIs offer? Not the GET vs. POST. Not even hypermedia, though I find that aspect interesting for some API use cases. What does it offer to everyone involved?

For us to answer that, we must meet people where they are. What is interesting is that this isn’t the first time this theme has emerged in my life. For about five years, I wrote and coached individuals on volunteer management. While the topic was related to churches, many of the principles translated to the non-profit sector in general.

I was always asked about how to recruit volunteers, keep them engaged, and ensure that they had a place to land once their season of involvement with the organization was done. My advice generally came down to the following: you need to meet them where they are at, examine the unique skills they bring, and find ways to help them make a difference. Everyone is designed differently. You, as the leader, are required to adapt to their gifts and passions. Not the other way around. Otherwise, volunteers will leave and never come back.

For our APIs to be successful, we have to speak in terms that everyone on the team will understand. Help them realize their passions and what they want to do. You must adapt to the audience, not the other way around. And your documentation needs to reflect that as well.

Finding new ways to communicate our API’s skills

At this stage of my career, I’m an API consultant. I love helping teams understand how to align their business, product, and technology choices. My consulting focus is to help teams to think in APIs. I spend a considerable portion of the time teaching teams how to model and design APIs. I see myself as a product architect, helping teams to find what they do best (their capabilities), and find ways to build an API strategy around those capabilities.

Keith and I captured many of these steps in our book, “A Practical Approach to API Design”. In the book and during our hands-on workshops, we teach teams how to break down the jobs-to-be-done into steps. We then map those steps into API endpoints. The result is the beginnings of your API design, documentation, and vocabulary for how your API skills will be used – all centered around the skills of your API.

What we seem to lack is an easy way to map these endpoints and skills into the documentation, typically Swagger. ALPs may be a solution to this approach as it separates the semantics from the API design. I hope to explore more about this soon.

For now, I am recommending that teams adjust their way of communicating by focusing on API skills first. Begin to orient your discussions around them, so that everyone on the team can participate and understand the conversation at hand. Allow your project managers to understand the impact of a new endpoint by discussing the new skill or capability that it brings to the business. Next, integrate the skills into your documentation to provide better clarity and spark conversations outside of HTTP design details.

Kin Lane has been taking this approach with his university API workshop. He mapped out some Zapier triggers based on the skills or jobs that they perform:

Jeff Barr recently posted this tweet of how the AWS API is being used from Alexa to enable VoiceOps:

VoiceOps is here – “Alexa what’s the instance count?” https://t.co/0ZRnyQijyg pic.twitter.com/AcJUcKWp1v

— Jeff Barr (@jeffbarr) March 21, 2016

The interesting thing here is the mapping between the job-to-be-done, the AWS API, and Alexa’s Skills Kit (ASK) that enables it all to work together. I hope to write more about this soon.

Educating everyone on your API’s skills

Call them skills. Call them activities. Call them capabilities. But let’s stop discussing our APIs in terms of endpoints made up of URLs and verbs. Instead, let’s start talking in terms of API skills and mention those URLs and verbs only when we need to be specific about the technical details. When we do this, we can start to educate everyone on the team about how APIs work, why improvements are necessary, and the reason why the product and business should care. Your product team and customers will appreciate it.

Thanks to Kin Lane and Lorinda Brandon for the additional inspiration on this article.

Photo credit: Skills – Graffiti doodle by DeaDerV23