{"API Evangelist"}

My Dream Stack For Machine Readable APIs.json Properties

The properties of each API that is listed in an APIs.json file can be called anything, as long as you preface it with X-, and the URL can point to anything you wish--to me this is one of the most flexibile aspects of APIs.json. The majority of APIs.json API properties are going to be to URLs designed for human consumption, but the ultimate goal of the project is to establish a core set of machine readable URIs that will help move the API discovery conversation forward.

The first three machine readable properties for APIs listed in an APIs.json are:

APIs.json is not looking to provide the solution for the same thing that sensibly designed hypermedia APIs would bring to the table, and only interested in bridging the indexing of the API resources that are currently available. In this context, think of APIs.json as a switchboard, allowing us to navigate each of the popular API definition formats available to use in 2015.

The fourth machine readable property for APIs listed in an APIs.json is:

With APIs.json version .014, we now have a glimpse of the surface area of APIs present within each APIs.json file, via the API Blueprint, Swagger, and RAML properties, and a basic awarness of the licensing of this surface area using the API Commons property.

I’m not 100% sure what is next for APIs.json property types, but if I had my vote (which I probably do ;-), I’d be interested in seeing machine readable references to:

For me, APIs.json takes the API discovery conversation beyond just the meta, which, don’t get me wrong is super valuable, with titles, description, tags, and other characteristics of APIs are critical to discovery, but I want to also be able to go deeper than just a simple keyword search. I want to be able to dig in on the areas above, but in a machine readable, bottom up, organic way.

I want to be able to ask for:

A number of conversation I have had around APIs.json with technologists almost always begins with a very technical API discovery discussion, something that quickly expands to the wider vision opened up by APIs.json around value generated by APIs, limitations imposed by the legal layer of platform operations, and into how we actually connect with valuable API resources. There are many more influences that prevent me from connecting to APIs, than just the technical aspects of integration—pricing, TOS, privacy, rate limits, and other business and political limitations often trump the tech when I select API platforms.

I’m still working through exactly how to best articulate Steve and mine’s vision for APIs.json. I appreciate you listening to my thoughts, as I work through the details, and I would love to hear more of your thoughts around what APIs.json means to you.