Jon Soeder

Technologist, People's Champ

Github's API is awesome

Github's API is a shining example of how a company can release an API for their service, and in the process empower everyone who uses it to use their imagination to come up with their own solutions.

Their documentation, client libraries, support, and the technical design behind it are all stellar. I personally have about ten different ideas that I would love to build ontop of the Github API, addressing software needs of programmers, writers, lawyers, law makers, students, etc.

The most powerful feature of their API, doesn't yet exist.

I would really like to see certain API endpoints, such as the Issues endpoint, Milestones endpoint, Pull requests, etc, have some kind of support for attaching searchable metadata. A small key value object, or a JSON object with some size constraints, will be more than enough.

The purpose of this metadata would be so that people could add their own tags, attributes, flags, statuses, descriptions, etc to the Issues or Pull Requests but not have those items degrade or in any way get in the way of the Official Github Experience offered by the various official clients of theirs, such as their website.

API clients, though, could use these endpoints in new and powerful ways that would likely lead to improvements in the official Github experience.

Currently, to provide this, I need to have a 3rd party service running.

It would be great to have this in the official APIs.

One specific Use Case

I want to use the Github API to manage all of the issues across all of my repositories. I use a system of custom labels which note status, priority, and things of that nature.

This just ends up cluttering the official interface. A better solution for the people for whom open/closed statuses, and labels are not sufficient, would be to have a metadata object attach to every issue that API clients could manipulate.

Another, much less intrusive solution, in my opinion, would be to support YAML frontmatter preambles in all markdown fields.

This would look like:

---
status: my custom status
priority: some other priority
notify:
  - project-manager@architects.io
  - customer@architects.io
screenshots:
  - url-to-image-1.jpg
---

### This is the body of my issue

I can type whatever I want

Now, in the Issues API endpoint I can do:

issues = github.issues("architects/skypager", meta: { status: "my custom status" })

issues.each do |issue|
  issue.update(meta: {status: "something else"})
  issue.send_notification_to(issue.meta.notify)
end

Hit me up Github

I'll develop these features for you for free if you give me the keys.

My email is jon@chicago.com