API Lifecycle Management

Fostering an API Community of Practice


This article by Shelby Switzer talks about fostering an API Community of Practice.

What’s the Community of Practice? 

A community of practice is a group of people who share a concern or a passion for something they do and learn how to do it better as they interact regularly. It is people who share a common interest. They have to be practitioners, and there should be a core learning component. It’s about sharing knowledge and learning to do something better together through interactions.

API community of practice

It’s a group of people practicing the design, building, or use of APIs and learning how to do that better as they interact regularly. Bringing people together on both ends is critical for building a shared understanding and a shared language.

Why make a community?

APIs are all about machine readability. It’s about getting machines to talk to each other. But, in reality, APIs are for the people behind the machines. Communities of practice are a fantastic way to build a community within an organization to help people learn from each other, feel greater connections, have fun and be happier together at work. They’re also a great opportunity to help share best practices and create a culture around the API Standards that you’re trying to create; create a shared language and shared vocabulary, and get people using the same tools, the same approaches, and knowing how to talk to each other about them.

Also, people are your greatest resource. It’s important to acknowledge that and to put it into practice through communities of practice and investing in people.

Five steps to an API community of practice

When I started at US digital service, I was placed on the Centers for Medicare and Medicaid Services team. This agency manages all of the money around Medicare and Medicaid implementation, as well as the rules and regulations and support for states as they implement those Medicaid specifically and for the federal government as they implement Medicare. It’s a huge organization with a mix of Federal staff, full-time employees, and contractors. Within that, there are many teams. But there is no central API strategy even though there are dozens of internal and external APIs. As I was working on the Firebase API, I wanted to learn about the other existing APIs and the APIs being built. As I started researching, I realized there was no centralization. One notable practice was that everybody had their own authentication strategy. So even if you did have public APIs, if somebody wanted to use more than one, they would have to authenticate in completely different ways to those different APIs, which is a terrible user experience. Technical specifications were also varied. This was an opportunity for me to learn and put some good API practices in place.

Step 1 – Talk to people

I started talking to people and started investigative discovery work to figure out the APIs. I wrote a report recommending that we create an API catalog across organizations, so we can keep track of who owns what API and get the documentation. While you talk to people, listen to people. It is important that you don’t start pushing your ideas and practices on them at the outset. You have to understand their business context, the problems they are trying to solve with their API, their constraints, and the reasons behind their design decisions.

Step 2 – Help other people listen

As a community of practice convener, you must be a catalyst for connection and give people opportunities to listen. As you become aware of what’s happening across your community, you need to be proactive about helping people form connections and meet each other outside of whatever big events you might be engaging in. It is important that people become resources for each other. If you want to scale out cultural change across the agency, you have to teach people how to be ambassadors of that change; you have to help them be the change you want to see.

Step 3 – Inclusive spaces

Inclusive is not just a buzzword. It is about safety and codes of conduct. It is not ensuring that diverse voices are represented. You should definitely be doing that, but also from an API and team perspective, ensuring that you’re including both the business and the technical side and your conversations that you’re including both the users and the builders. It’s also about making sure that you do have accessible presentations. It is about creating a baseline for community norms so that people have an understanding when they come into the space of how they should interact respectfully. It’s important to have people involved in co-creating these inclusive spaces. Help people take ownership of the community, make them feel like they have a part in it and are influencing it, which will make them much more engaged with the community itself and more engaged with the content from learning for each other.

Step 4 – Curate content intentionally

Don’t hope that people bring good content. You have to work with them to ensure that they are telling a good story, basing their content on actual experience instead of hypotheticals, and bringing something relevant to the group. That could also involve doing some brainstorming with them. It involves you going out into the community to find those stories that people may not realize they have.

Step 5 – Institutional Support

Even if folks don’t need permission to participate in something, they still benefit from encouragement to participate. Everybody needs to feel competent and that the leadership cares about the community effort and the initiative. That permits them to take time out of their busy day to block off time for the monthly meetings and events or even contribute to a community project.

But it’s not just about showing institutional support. You have to enact institutional support for community-building initiatives. To maintain the community, you could set up rotating leadership of your community or practice. You can have a rotating committee of people where you have one person facilitating for the first three to six months, and then it transitions to another volunteer. That way, it’s never too much burden on one person. It’s never seen as a long-term commitment but gives somebody the time and opportunity to try out new skills, such as community facilitation, or focus on something they care about.

Shelby Switzer
As a fellow on the State Software Collaborative, I advance research around and create practical resources for state, territorial, local, and tribal governments seeking to build software collaboratively with each other.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture