APIs.json lets domains make their APIs public and discoverable by search engines.
APIs.json is an API definition format and associate file used to communicate what APIs are provided by a domain. The file resides in the root of a domain, containing a machine readable description of the APIs and links to other similar files. APIs.json is similar to robots.txt used by search engines to index a website’s content, but it applies to API discovering and indexing.
Although APIs.json has reached only version 0.14, the authors consider it “ready for prime time” and “something the community can really build on.” The format defines a number of mandatory or optional elements from which we quote only a few:
- Name [Mandatory]: text string of human readable name for the collection of APIs
- Description [Mandatory]: text human readable description of the collection of APIs.
- Created [Mandatory]: date of creation of the file
- Apis (collection) [Optional]: list of APIs identified in the file, each containing:
Name [Mandatory]: name of the API
Description [Mandatory]: human readable text description of the API.
baseUrl: Web URL corresponding to the root URL of the API or primary endpoint.
Version [Optional]: String representing the version number of the API this description refers to.
properties (collection):
- type: please see reserved keywords below.
- url or value.
APIs.json is the result of a joint effort by 3Scale (Steve Willmott -@njyx, Nicolas Grenie -@picsoung) and API Evangelist (Kin Lane -@kinlane). InfoQ has interviewed Kin Lane to find out a few more details about this project.
InfoQ: Do you intend to submit this format to a standardization body?
KL: Submission to a standardization body is one possible future for APIs.json. For right now we are just working to get as much feedback on the format, and mature it through the deployment across 1000’s of domains, then we will consider next steps.
InfoQ: Are there websites already using this format?
KL: The first was apievangelist.com, and there are 138 APIs submitted from 98 separate providers, but many are not from the authoritative providers. Meaning they were submitted by an outside party. However there are many authoritative APIs.json from providers like Spotify, Diffbot, Paypal, MYOB, and Neutrino API.
InfoQ: Why is the current version marked as 0.14 as long as you deem it "something the community can really build on." Shouldn't it be v. 1.0?
KL: We start with version .11, and quickly iterated through feedback and several events to get to .14. Until it is widely used, and something that hundreds of providers have agreed works, a 1.0 version just doesn’t seem appropriate. We’ve had a long couple of months to get where we are at, but we have a lot of work to do still.
InfoQ: I see that APIs.json supports the following API formats: Swagger, RAML, Blueprint, WADL, WSDL. Do you plan to support any other format in the future?
KL: We are focused on the leading API definition formats at launch. However using the API properties you can specify any API definition format you choose. There are no limitations, and once we see a certain definition gaining steam in usage, we’ll include them in the core spec.
InfoQ: What are your plans for the near and long term future?
KL: Implementation. Implementation. Implementation. We are educating API providers about APIs.json, and helping them implement. We will be focusing on helping people understand the benefits around the internal usage of APIs.json, as well as for public discovery. Along the way we will be continuing to work on meaningful tooling, like open source search engine APIs.io, that helps people see the benefits of APIs.json.
APIs.json is accompanied by APIs.io, an open source search engine that crawls the web to index the apis.json files it discovers. The website also contains a number of tools for registering new APIs, then generate and validate apis.json files for them.
The entire APIs.json project is open sourced on GitHub under the MIT license.
