To help drive the discussion I am wanted to use the OpenAPI Specification that I created for HSDS, and I also knew I wanted to use Github issue management to help keep track of the synchronous, and asynchronous conversation that would occur around it. However Github tends to have a perceived barrier to entry for many non-developers (which I don't fully get), so I wanted to leverage the platform, but also soften the way everyone discussed the overall specification, as well as each individual endpoint.

Resulting in my APIs.json Annotation tool. It is just a first draft, so there will be a lot of changes that need to occur. I'm going to test it against 20+ APIs.json collections I have defined as part of my API Stack work to try and harden it a little bit. My APIs.json Annotation tool runs in my single repo app style, leveraging Jekyll + Github Pages + Github API to operate--Github is the front and backend.

Anyone can view the conversation, but if you want to participate you have to be added to the Github repository, and pass in a Github personal token. This is something I often automate with a simple Github login, where I use OAuth.io to obtain token, but I kind of see the token as a minimum viable investment to understanding Github for using each tool.

It is really important to me that each app stands on its own feet. Not all of my micro tools that I develop in this way will enjoy zero outside dependencies, but most of them can be easily forked, and ran in any Github user account or org (with little or no setup). Conversations around API is just one area I am looking to simulate with this approach to delivering tooling, and specifically APIs.json tooling, that can be used throughout an API life cycle.