In developer relations, we root our work in community. We treat our community of experts as our friends, neighbors and colleagues. So, it made me wonder... how do we design APIs that treat our community like a best friend forever (BFF)?

If the core component of any platform are APIs, then these APIs should be a BFF to our community. To me, a best friend is reliable, anticipates your needs, is always easy to catch up with after time apart, and never misses an opportunity to make you smile. The communities we support deserve APIs that treat them like the best friend they are. This is the golden rule of ecosystem API design and development.

I know I can rely on you.

A key part of being a friend is being reliable. Our APIs first and foremost need to be reliable for our community. My API BFF should let me know what to expect, we should think alike, and I know it is always there for me when I need it.

Expectations

Just like with your IRL (in real life) BFF, you know at their core who they are and what they are about. Our community APIs should do the same. By utilizing specifications like the Open API Initiative, communities have immediate documentation and understand the interoperability of your APIs. Leveraging Open API Specifications to design APIs from the beginning can help you nail down your naming conventions. You should also leverage standards from REST and GraphQL so your community can have standard nouns and verbs to rely on. Plus, whether your API is REST based or GraphQL based there are Open API Spec Tools available.

Thinking Alike

Now that you and your API BFF are on the same page, your APIs should be designed in an intuitive way; community users should be able to make assumptions about how the API works overall and be right most of the time. Studies have been done that show our closest friends actually think like we do. Taking this into account, we need to be aligned with our community in order to achieve the level of "best friend" status.

Developer Advocates can help foster API befriendment by connecting community to feedback mechanisms and clarifying content. Community engagement and reciprocity is crucial here. To have an API that your community loves, focus on ensuring that you and your community are jiving on values, opinions, and interests - as these are proven to be inherently rewarding according to Carolyn Parkinson from the article referenced above.

Always There

This will be short and sweet. Friends don't just leave you hanging. They communicate issues and try to resolve things quickly. So ensure your community has access to API status page and the messages are clear, concise and constructive. Aim for 5-9's (99.999% uptime) but ensure you have a strategy for when plans change.

You always understand me.

Just as your community should be able to easily understand the API Specs and conventions, your APIs should understand the communities needs and be designed to provide that.

What I Need and Want

Allow your community the option to query, sort, and filter API results to get just what they need and want. Just don't make too many assumptions on how your community will want to interact with a specific API. This helps your API not feel overly chunky or too chatty. You don't want your community to have dig through complex objects to find what they are looking for, or make 10 calls for what could be a single object. You don't want so many endpoints that tasks become difficult to chain.

I miss you when we are apart.

Community members may not always be utilizing your APIs everyday to solve thier problems. You may have community members that leverage your APIs more sporadically than others. Just because your BFF comes and goes doesn't mean they don't care. These community members can be super evanglists that are sending other developers your way. They just have other things going on, you know? So, keeping these sporadic users in mind is important.

Catch Up Easily and Quickly

Documentation should be memorable to your community. This should be your go to meet up spot. It should be welcoming and fun. The information in the docs should also have a way of structuring what you want new and old friends to know. Therefore, make it easy and quick for community members to catch up on the latest changes. (Changelogs are great for this.) Your documentation architecture should leverage the API specs we already talked about... so ensure your API docs are utilizing them for a reference in your documentation.

I personally like the highlight reel approach. I find in conversations with friends, that I haven't spoken to in a while, we start by talking about the big things before moving onto the details. I think similarly about great API developer docs. They have a similar conversational type structures and call out big life changes. Great docs will be detailed and have statuses or badging that call out right away when something major happened, like deprecation, or your API is moving to a new version.

You make me feel safe and secure.

My best friends make me feel like I can share anything. Our community API's should be able to accept sensitive data without risk. We need to ensure that our API design accounts for various levels of auth and security where required. This also shows you care about your community's data, which is never a bad thing.

Did we just become best friends?

By designing and maintaining API's in the same way we cultivate friendships, we can create a developer community that loves using our APIs. Developer communities and the tools they use have a connection that mirrors friendships. Great API designers use this to their advantage. If we keep this in mind, we can become best friends with our communities.

BFF's this is a Presentation Too!

If you would like me to give this presentation live - reach out to me: Rachael Thompson