The API Handyman AKA Arnaud Lauret, recently posted an excellent writeup discussing the difficulties API designers or design reviewers encounter when they venture into the realm of preference and opinion.

This post is a response and extension of his. If you haven’t then go read it, it’s short and good, I promise it’s worth your time.

Like Arnaud, I’ve performed this function in many organizations large and small for years and there’s a critical point he (likely purposefully) left out.

Errors and ambiguities in your design requirements, guidelines, and common practices prevent objective review process, setting teams and reviewers up for opinion oriented discussion.

Here’s the important thing to understand as an API designer; ambiguous design requirements and responsibilities are the primary genesis of these situations. The team’s seeking your help aren’t at fault, they simply followed your requirements in ways you didn’t anticipate. Take these occurrences as the gifts they are, they have shown you where your guidelines, processes, and procedures need further refinement.

As the old joke goes naming things is one of the hardest tasks in computer science. People have vastly divergent backgrounds and will interpret requirements differently and create wildly varying output.

Try to look at your guidelines through the fresh eyes of your newest users’. Do your best to avoid looking at with your experience and knowledgeable perspective.

Preferences and opinions have a place in API Design practices, there’s quite often many ‘right’ answers. Ultimately, it comes down to the API owner making a choice. When things works out that way, try out Arnaud’s advice. I think you’ll find it helpful.

Just make sure you don’t forget to look at each occurrence and question if the guidelines and requirements you’ve established led to an opinionated decision that should and could have been made based on facts too.

Watch for patterns of behavior from different teams and people that run counter to your expectations. Always look for places to develop your coaching strategy to get more mature designs from your teams. While you’re helping teams through your process, don’t forget that you’ve also got a lot to learn, so you shouldn’t waste the precious feedback your process produces.