{"APIs.json Annotation"}

Fork on Github

APIs.json Annotation

I wanted a way to have a conversation around an API design with a group of folks. Some who are technical, but others who are not. I also wanted to use Github issues to help manage the ongoing conversations around the API and its design. I got to work building one of my micro tools to help me manage the process, in a way that can easily be forked and run for any project.

This tool runs 100% on Github pages, leverage JavaScript and the Github API to do what it does. Users who have been added to the repo, can pass in a personal token using the "token" query string variable, and then will be able to annotate and comment on each endpoint.

All annotations to each endpoint are just added to this Github repos issue management system, using the path as the title, and applying the HTTP verb as a label. You can access everything under issue management, in the Github repository for this project.


Annotations For This APIs.json

Click on a message bubble next to any of the end points on the left to see any annotations that have been applied to any of the endpoints.

If an endpoint already has been annotated, you will be able to comment on the thread, or visit the issue on Github.

You can fork this project, and run under your own account, on your own APIs.json index. I am just exploring different ways of working with the surface area of an API, using machine readable API definitions like APIs.json and OpenAPI Spec.