Distributed Web API discovery

The site apisjson.org defines a specification for creating a document that declares the existence of an API on the web.   This document provides some identification information about the API and links to documentation and to the actual API root URL.  It also supports pointing to other resources like API design metadata documents and contact information for maintainers of the API.

Here is a fairly minimal version of what the declaration document might look like for the Runscope API.

{
  "Name": "Runscope APIs",
  "Description": "APIs for interacting with Runscope Tools",
  "Tags": ["testing", "http", "web api", "debugging","monitoring"],                            
  "Created": "06/12/2014",                                                                  
  "Modified": "06/12/2014",
  "Url": "http://api.runscope.com/apis.json",
  "SpecificationVersion" : "0.14",
  "Apis": [
    {
      "Name": "Runscope API",
      "Description": "An API for interacting with the Runscope HTTP debugging, testing and monitoring tools",
      "humanUrl": "https://www.runscope.com/docs/api/overview",
      "baseUrl": "https://api.runscope.com/",
      }]
    }
  ]
}

There is an experimental search engine available that maintains a list of links to these API declaration documents and makes the contents searchable.  If I were to take the JSON above and expose it at https://api.runscope.com/apis.json and then submit that URL, the search engine would index my declaration file and allow users to find it.

The important bit

One of the best parts of this specification, regardless of the fact that it is still immature and I’m sure has many more revisions in front of it, is that the authors are really trying to embrace the way the web is supposed to work. 

• They have identified the focused scenario of “api discovery” that can take advantage of a standardized solution. 
• They are taking no dependencies on tooling or frameworks. 
• They are considering registering this as a standardized IANA media type. 
• They are recommending the use of a standardized link relation types described-by to allow APIs to point to their own declaration document to help make APIs more self-describing. 
• They are considering making use of well-known URIs as a way to allow crawlers to find these API declaration documents without needing them to be submitted manually.
• The specification is being developed in the open. They have a github repo and a Google group where they are accepting and acting on feedback they receive and they are iterating quickly.   

This is how web work should be done.  By building on the conventions and standards that others have already produced instead of re-inventing and fragmenting.  Kudos to Kin Lane and Steven Willmott for pioneering this effort.  I look forward to many more people getting involved to make this successful.

Now if only we could find a better name for the format 🙂

Image credits: Earth https://flic.kr/p/8FnV8