{"API Evangelist"}

API Police Report: Raw Thoughts From On-Boarding With Your API

I am working hard to generate detailed profiles, that include APIs.json indexes, and Swagger definitions, for each of the 1000 companies I have listed in the API Stack. I have encouraged anyone to step up and help me profile these companies, join the conversation via the Github issues where the API stack is hosted, resulting in some really nice folks jumping in to hellp me tackle the hard work.

One of these brave souls who stepped up, and get their hands dirty is Bob Salita, who is also sharing his experience, via what he calls an "API Police Report", derived from his experience onboarding with APIs. I thought his condensed thoughts reflect what I see everyday as I onboard with new APIs, and was worth sharing.

He starts with a simple question: What do developers want?

What do we force a developer do?

What you can do! Anticipate needs, minimize process:

The anti-patterns to onboarding:

What Are The Best Practices:

Sometimes you have to be a snob – for good reasons:

I am just publishing his raw report as is, because I think it reflects what a tough job it is to profile these APIs, and the thoughts that go through your head as you do the work. This work is something API providers should be doing themselves! They should be going through their APIs, putting on their external developer hats, and try to think like a new developer might--experience the friction.

The process of trying to understand what an API does, how to get access, and the process of indexing the API operations using APIs.json, and craft individual Swagger definitions for each available APIs is a lot of work, but it represents the work, and thought you should be putting into your API--it is an important journey!

I will be referencing these "API Police Reports" in future stories, because Bob's honest thoughts, as he does this hard work, provide a wealth of detail that all API providers should be tuning into.