{"API Issues"}

Using My APIs.json Annotation Tool To Drive An API Design Conversation Via Github Issues

I am working on one possible API definition for the Human Services Definition Specification (HSDS), and the next phase of this work involves bringing in a small group of technical, and non-technical folks to have discussions around their API designs, in context of the master specification I am looking to pull together. 

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.

The HSDS specification is pretty verbose, and I needed a way to have conversations at the high level, but also down to the endpoint level. To help facilitate this, I got to work on a prototype micro tool which enables a conversation around any API(s) that are indexed within an APIs.json file, producing a human readable list of endpoints, parameters, etc., but then uses Github issue management as the core of the conversation. 

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. 

You are welcome to play with the APIs.json Annotation, or any of the other tools I have listed on my home page. I will keep adding them here, so that they can be found, but like all my work they are all a work in progress. Each tool has its own dedicated repo and issue management, where you are welcome to join in the conversation around the road map for each one. I am just looking to develop a robust toolbox of small micro tools that will help be more successful across the life cycle of the APIs I am working on, but maybe you can benefit using them too.

See The Full Blog Post


From Github Issue To Story to Resource

As an evangelist, your responsibility is to get the word out about an API, and provide users with the resources they will need to be successful.

While executing on your evangelism strategy, there are numerous ways to generate stories for your blog, but one of my favorite approaches is to cherry pick the best issues on your Github repositories.

If you are like me, your using Github repos to manage everything from documentation and code samples to presentations and terms of use. One of the perks of using Github, is you immediately gain the benefits of the Github issue management system.

While many of the issues submitted on your Github repos will be mundane and not very story-worthy. Always keep an eye out for ones that are ripe for picking and turning into an actual stories for your blog and social media accounts.

Earlier today, I received some great feedback via the issue management system on the API Evangelist repo. Ben Balter (@benbalter) from Github recommended that I use a permalink frontmatter to simplify my file structure. In my migration from a PHP blog to using Jekyll on Github Pages, I hadn't considered this, and when I learn something new, I want to share it by crafting into a story and posting it on the blog.

Not only will this Github issue become a story, providing much needed SEO and education for my users, I will also turn this into a more structured resource, and provide as part of future educational content.

Pulling stories and educational content from relevant Github issues can be a great way to generate valuable content for your platform, and if it is done in real-time it isn't really that much work.

See The Full Blog Post


API Issue Management Using Github

Github should be the center of your API operations, with the most obvious use being for SDK repositories, but Github offers a lot of other valuable tools that you can use to manage your API platform.

One great use of Github is as an API issue management tool. The Github issue management system allows you to easily accept issue reports from your API community and apply labels to organize them into appropriate categories, for processing by your development team.

To setup Github Issue Management for your API, just create a new repository, but you won't actually being pushing any code, you will just be using it as a container for running issue management. Think of it as repository for your API itself.

Once setup, you can link the issue management page directly from your API area, allowing users to actively submit issues, comment and potentially be part of the API product development cycle.

See The Full Blog Post