A Breakdown Of My Dream APIs.json File

I'm continuing my work, to help people understand what APIs.json is, and the varying ways that it can be put to use. My post the other week, breaking down Fitbits APIs.json file is a good example of where to get started, and as a follow-up I wanted to help further set the bar for what a minimum viable APIs.json looks like, and today, I am going in the other direction--toward my dream APis.json file.

APIs.json starts with a basic set of descriptions for who you are, the API provider. Each header of an APIs.json file gives you a handful of parameters for describing who you are:

Those seven parameters provide details on who you are, and what the API collection is all about. Remember an API collection doesn’t always have to live under a specific company domain like Twilio.com, it could be a temporary or more permanent collection, that is part of specific project or application.

The next essential element of an APIs.json file, is the APIs collection, providing you the ability to describe one or many APIs as part of this collection. Similar to the parameters provided for the header, each API entry is allowed a handful of parameters that describe the API:

Each API should have at least this information, at a minimum. I could stay here, with a minimum viable APIs.json definition, but I encourage you to take one more step, and put the properties collection to use for each API. You can provide any other URL you want for an APIs properties, but I recommend starting with the basic properties:

These are meant to satisfy the common needs of anyone learning about API operations, however they are just URLs meant for the human API consumer. In my dream APIs.json file, there will be a robust amount of machine readable properties available for each API, beginning with the two most important:

Along with providing machine readable definitions of the API surface area, establishing a central truth or fingerprint for any API interface, it is just as important to provide a machine readable license for the API:

Along with making sure the interface of an API matches your application objectives, consumers need to understand the licensing restrictions, or the freedom that comes with deeply integrating an API resource into any system or app.

Since I’m talking about my dream APIs.json file, I’m going to talk about two added property formats I’m currently working on behind the scenes, adding to the stack of machine readable API definition formats.. These new areas, represent two areas I’m working hard to define and understand, right after I hand-craft Swagger definitions for my APIs:

Can you imagine if API pricing was machine readable by default? Think of the options for building in a broker or market layer within the index of API platforms, and API collections, or even via an IDE. These two definitions are in an alpha stage, but are based upon data I've been gathering behind the scenes, so a lot of thought has gone into settling on these buckets.

After that, I’d say there are a handful custom properties I’d like to see applied to each API indexed within an APIs.json:

That concludes my list of elements I’d like to see available in my dream APIs.json file. You can see examples of this in action, with the 700+ companies I've generated APIs.json files for, over at my API Stack Github repo. There is a lot of work left to do, but this dream APIs.json file resembles a vision I have for the future of API discovery—which I see as the engine for the API economy.

My goal is to get there I need the most important aspects of API operations machine readable. We aren't there yet, but I can see it. Taste it. Imagine what we can do when you can program against:

I have been staying in tune with the API space using RSS feeds, and the Twitter and Github APIs for a couple years. I’m just now developing a deeper understanding of the overall API space through the generation of machine readable API definitions for popular APIs. I can’t do much on the API licensing front beyond launching API Commons, but I am working to define pricing with my api-pricing definition work, and also trying to capture the vital meta-data I need about API operations using api-questions.

This post ended up being longer than I anticipated, but it is helping me beter understand what some of the next steps are for not just APIs.json, but also my own monitoring of the space. My goal is to not just push forward the APIs.json definition, but push forward my understanding along the way. Who knows maybe I'll drag you along too! ;-)

Ok, back to work. I just needed to wrap up these two posts about APis.json that were lingering in my outgoing story and idea queue.

Return to Blog