Draft for Comment Name: API Discovery Format Informal Name: APIs.json Authors: Kin Lane, Steven Willmott, TBD Date: Location: http://apicommons.org/apisjson/apisjson_v0.1.txt A Simple Format for Publishing API Meta Data on the Web Table of Contents 1. Abstract 2. Introduction 3. Specification 3.1 Access method 3.2 Authority 3.2.1 Authoritative 3.2.2 Non-Authoritative 3.2.3 Conflict Resolution 3.2 File Format Description 3.3 Formal Syntax 3.3.1 JSON 3.3.2 Text Format 3.4 Expiration 4. Examples 5. Security Considerations 6. Reserved Keywords with Definitions 7. References 8. Acknowledgements 9. Author's Address 1. Abstract Web APIs [1] are becoming a crucial part of the Web. Unfortunately however, it remains very difficult to determine the location of these APIs on servers around the Web by automated means. The only way to discover APIs and their properties is via human driven search through public search engines or in hand curated API Directory listings such as ProgrammableWeb [X]. While these methods work, neither can scale to the potentially hundreds of thousands and millions of APIs which will be published over the next few years. The objective of the format described in this document is to provide a simple means for individuals and organizations to document the location of their API Services on a given domain in a machine readable way. The format is designed for public deployment and for consumption by automated software agents (robots). This document is written in loose RFC style for the purposes of clarity, but it is not an official recommendation. Discussion around the format takes place on the API Commons mailing list [REF-Kin]. 2. Introduction Web APIs have quickly become and important part of Web Infrastructure. However the amount of machine readable meta-data about the location and capabilities of these APIs remains extremely limited. A number of machine readable formats for describing Web API Interfaces have emerged. Unfortunately however adoption of these formats is not widespread and further, where they are used it is in turn not clear where to look for these definition files themselves. This document takes no position on which of these formats is best, but aims to solve the problem of where to find the descriptions in the first place. In other words, it means to provide a mechanism to bootstrap meta-data discovery for APIs. The objective of the format defined in this document is to provide a lightweight means for individuals and organisations to document the location of their APIs, the associated descriptions, human and machine readable specification and ancillary information (such as licensing, maintainers and so forth). 3. Specification This section defines the API Meta Data Format. The following terminology is used throughout: * File: instance of a digital file containing data. * Apis.* file, a file which contains API Meta Data information compatible with this document and uses one of the definited content types [currently JSON and TXT]. A file may contain more than one API Specification. * API Specification: collection of information about a specific API expressed in the format defined in this document. Uniqueness is determined by the primary root/base URL of the API. 3.1. Access method The definitions of API Meta Data must be accessible by HTTP or HTTPS or Both [X] from either the site on which the referenced APIs are operating or another site (see below for information on Authoritative and Non-Authoritative definitions) as a resource of Internet Media Type [3] as determined by the content type (see section XX) under a standard relative path on the server: "/apis.*", where * is determined by the content type of the file. For convenience we will refer to this resource as the "/apis.* file", though the resource need in fact not originate from a file- system. Some examples of URLs [4] for sites and URLs for corresponding "/apis.*" sites: http://www.foo.com/apis.txt hhttp://www.bar.com:8001/apis.json If the server response indicates Success (HTTP 2xx Status Code,) the robot must read the content, parse it, and follow any instructions applicable. If the server response indicates the resource does not exist (HTTP Status Code 404), the robot can assume no instructions are available. If the robot parses the file it may discover references to further apis.* files elsewhere on the same filesystem or elsewhere on the Internet. It may choose to download these files also and take into account the information contained within them. While the format is intented to be human readable and may be used by humans, it is primarily intended for consumption by automated software systems. Such software systems may be part of search engines, testing frameworks or API using applications. In keeping with terminology from the robots.txt format they are refered to as robots from here onwards. 3.2. Authority 3.121 Authoritative An entry in a apis.* file is AUTHORITATIVE for a given domain if the root domain of the API described by the entry is on the same DNS domain or on a DNS subdomain thereof. 3.2.2 Non-Authoritative An entry in an apis.* file for an API is NON-AUTHORITATIVE if it is not AUTHORITATIVE. 3.2.3 Authority by Reference [We may wish to allow the case where a top level apis.json file on a given domain has pointers to files on other servers which define APIs on the domain of the first file. These could then be considered authoritative. This is complex but might be a real use case.] 3.2.4. Conflict Resolution In cases where a robot discovers more than one entry in seperate apis.* files for a a specific API, priority on the validity of information should generally be resolved as follows: * Authoritative entries have priority over non-authoritative. * Where two or more authoritative entries exist on different subdomains, the entry in the file closest to the specific domain of the root domain of the API shall have priority. Example for an API with DNS domain http://mainapi.commerce.company.com/ where entries are present at: * http://company.com/apis.json * http://commerce.company.com/apis.json The later would be interpreted as the most Authoritative. 3.3. File Format Description 3.4. Formal Syntax 3.4.1. JSON Format This is a proposed specification for an api.json file, which can be placed in the root of any domain, providing a single inventory of all API resources available within that domain, as well as pointers to other associated api.json files. A file shall be in json format and contain the following elements: * name [Mandatory]: text string of human readable name for the collection of APIs * description [Optional]: text human readable description of the collection of APIs. * Image [Optional]: [[[what is this for?]]] * url [Mandatory]: Web URL indicating the location of the latest version of this file * apis (collection) [Mandatory]: list of APIs identified in the file, each containing: * name: name of the API * description: human readable text description of the API. * image: URL of an image which can be used as an "icon" for the API if displayed by a search engine. * humanUrl: Web URL corresponding to human readable information about the API. * machineUrl: This is either a link to a primary machine readable definition of the API (if so, those referenced in URLs are treated as secondary), or it is the Web URL corresponding to the ROOT of the API itself. This element determines the uniqueness of the API. [[[[STEVE: this one is very important]]]] * tags (collection)" [[[STEVE: is this a collection?]]] * urls (collection) - type: please see reserved keywords below. - url * contact (collection) - type - url * meta (collection) - key - value * include (collection) * name: name of the APIs.json file referenced. * url: Web URL of the file. * maintainer (collection) * type * url [[[STEVE: Does this need more structure?]]] * tags (collection): [[[STEVE: is this a collection type?]]] * modified [Mandatory]: date of last modification of the file The above elements determine the information to tbe provided (examples are provided lower down). In addition the format reserves keywords for types. These are listed in Section 6. 3.4.2. Text Format A Text format is planned, using similar syntax to robots.txt. 3.4.3. Presence of Multiple Formats In cases where multiple apis.* files of different formats are present on the same DNS domain, the robot may assume that the information in each is identical appart from format and read any of the files, ignoring others. 3.5. Expiration Robots may cache /apis.* files, but if they do they must periodically verify the cached copy is fresh before using its contents. Standard HTTP cache-control mechanisms can be used by both origin server and robots to influence the caching of the /apis.* file. Specifically robots should take note of Expires header set by the origin server. If no cache-control directives are present robots should default to an expiry of 7 days. 4. Examples Here is the api.json for the API Commons: { "name": "API Commons", "description": "An API for adding and pulling APIs that are in the commons.", "image": "https://s3.amazonaws.com/kinlane-productions/api-commons/api-commons-icon.png", "url": "https://api-commons.3scale.net/docs", "apis": [ { "name": "API Commons", "description": "An API for adding and pulling APIs that are in the commons.", "image": "https://s3.amazonaws.com/kinlane-productions/api-commons/api-commons-icon.png", "human-url": "https://api-commons.3scale.net/docs", "machine-url": "http://api.apicommons.org/swagger-spec.json", "tags": "API, Application Programming Interface, Copyright", "urls": [ { "type": "signup", "url": "https://api-commons.3scale.net/signup" }, { "type": "swagger", "url": "http://api.apicommons.org/swagger-spec.json" } ], "contact": [ { "type": "email", "url": "apicommons@gmail.com" }, { "type": "twitter", "url": "https://twitter.com/apicommons/" } ], "meta": [ { "key": "interface-license", "vallue": "CC BY 3.0" }, { "type": "pricing", "url": "Free" } ] } ], "include": [], "maintainer": [ { "type": "Name", "url": "Kin Lane" }, { "type": "email", "url": "apicommons@gmail.com" }, { "type": "twitter", "url": "https://twitter.com/apicommons/" } ], "tags": "api, copyright, application programming interface", "modified": "04/07/2014" } Further examples can be found at: * [[[Any others?]]] * * 5. Security Considerations Deploying files compliant with this recommendation on your domain may generate certain security risks. The recommendation is not intended to protect APIs, other types of resources or secure access in any way. The objective of the recommendation is to provide simple means to identify where APIs may be located on a given domain. As such external parties accessing the specification files will be able to determine the location of the API endpoints referenced within the file and hence may attempt to access them. All such visible endpoints should be secured in an appropriate manner. 6. Reserved Keywords with Definitions The following keywords are reserved in all formats. * Swagger * RAML * WADL * ... * [[[STEVE: kin you have a list?]]] This list may be updated from time to time. 7. References TBD 8. Acknowledgements The specification provided here was inspired by conversation in the API Community at events such as the API Strategy and Practice Conferences, API Days conferences, Nordic APIs conferences, Gluecon, Defrag and others. 9. Authors' Address Kin Lane, API Evangelist http://www.apievangelist.com/ email: Steven Willmott 3scale networks http://www.3scale.net/ email: steve@3scale.net Nicolas Grenie, 3scale networks, http://www.3scale.net/ email: nicolas@3scale.net