The Five Month Journey Toward A Stable APIs.json Discovery Format

I published the story last night on finalizing the most recent version of the API discovery format APIs.json, and the support for it in the open source API search engine APIs.io. Steve and I are done messing with the format for a while, and want to encourage API providers to begin describing their APIs using the open format.

After publishing the story last night, I also had an interesting comment on Google+ from Jonas Hellström:

The question got me thinking about how APIs.json rolled out. As with API Commons, APIs.json started as a conversation between Steve Willmott (@njyx) and I. Around the beginning of April we combined our notes on what each of us envisioned when it came to API discovery, establishing the first APIs.json definition with the timeline going roughly like this:

  • April 2014 
    • Steve and I established version .11 of APIs.json
    • We emailed a handful of smart folks that we trusted for feedback
    • Crafted version .12 of APIs.json
    • Developed APIs.io
  • May 2014
  • June 2014
    • Establish version 0.13 of APIs.json
    • Continued discussion on Google Group
    • Continued feedback on Github issue management
    • Continued email conversations 
  • July 2014
    • Conducted a session on API discovery, including APIs.json at APICraft in Detroit
    • Tony Tam (@fehguy) for the work on the JSON schema (thank you Tony!)
    • Established version 0.14 of APIs.json
  • August 2014
    • Updated APIs.json for API Evangelist network to version 0.14
    • Updated APIs.io to support version 0.14 of APIs.json

It has been an interesting five months. I like to record things like this while they are fresh in my mind, because as time moves on, the details fade into the past. I feel like if I do not capture the moment, it will be forgotten and it will be like it never happened.

I think we got the feedback from the community we needed to get to the first stable version, and I want to thank @fehguy, @mamund, @darrel_miller, @OriPekelman, @xmlgrrl, @johnmusser, and the attendees at Gluecon, APIDays, and APICraft for listening, and providing feedback. Also thanks to Jonas Hellström for your great question!

It will be interesting to see what API discovery looks like in 2015--it is a very exciting time!