api-questions is my centralized, machine readable JSON format for storing the answers I need, regarding my APIs, and those that I track on as part of my monitoring. Each question is a simple question / answer, trying to keep things simple, yet machine readable.

api-questions was born out of trying to make a machine readable terms of service format, but after studying approaches like TOS Didn’t Read, I felt that if I made it about TOS, it wouldn’t be something end-users would pay attention to. To keep api-questions simple, and understandable, but make it also machine readable I wanted to distill it down to just the basic.

I’m answering just about anything I need to know about API operations using api-questions, from does an API have oAuth, to can I delete my account. I’m using api-questions to better understand how APIs work, and to develop an index that I can search against.

api-questions is a machine readable format, meant to live in the public repository of a micro-services Github definition. I’m referencing api-questions in my APIs.son format, allowing me to search for APIs with specific answers to questions, or even APIs who haven’t answered specific questions.

My goal is to develop a core set of questions, drived from what I ask of the APIs that I monitor regularly, then encourage API providers to answer the questions themselves. I will be hand-crafting the first wave of api-questions files for public APIs, but it is something I’m hoping will catch on beyond just my initial work.

Ultimately, I want to teach end-users to ask these questions of the platforms they use, always starting with the first question: Does this service have an API? Then from there, go deeper, and ask the harder questions like do I own my data, and can I take my data out of the platform. I want these questions to be accessible by anyone, but also allow for easy, machine readable access to the answers that are provided by api-questions.