From f196b0dafe9674b426cd8739c5957fe0f6238194 Mon Sep 17 00:00:00 2001 From: Kin Lane Date: Wed, 22 May 2024 19:41:32 -0400 Subject: [PATCH] add spec --- apis-json-spec.txt | 556 ++++++++++++++++++++++++--------------------- 1 file changed, 299 insertions(+), 257 deletions(-) diff --git a/apis-json-spec.txt b/apis-json-spec.txt index 14d5d94..ec25685 100644 --- a/apis-json-spec.txt +++ b/apis-json-spec.txt @@ -1,73 +1,73 @@ -Draft for Comment -Name: API Discovery Format -Informal Name: APIs.json -Authors: Kin Lane, Steven Willmott, Nicolas Grenie, Bruno Pedro -Date: 29/04/2015 -Location: http://apicommons.org/apisjson/apisjson_v0.15.txt +Draft for Comment +Name: API Discovery Format +Informal Name: APIs.json or APIs.yaml +Authors: Kin Lane, Steve Willmott +Date: 01/09/2020 +Location: http://apisjson.org/format/apisjson_v0.16.txt -A Simple Format for Publishing API Meta Data on the Web + A Simple Format for Publishing API Meta Data on the Web Table of Contents - 1. Abstract - 2. Introduction - 3. Specification - 3.1 Access method + 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.2 File Format Description + 3.3 Formal Syntax 3.3.1 JSON 3.3.2 Other Formats - 3.4 Expiration + 3.4 Expiration 3.5 Media Type 3.6 JSON Schema 3.7 Well Known 3.8 Link Relation 3.9 Extensions - 4. Examples - 5. Security Considerations + 4. Examples + 5. Security Considerations 6. Reserved Keywords with Definitions - 8. Acknowledgements - 9. Author's Address + 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 + 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 [2]. 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 + 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 + 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 Json Mailing list [3]. 2. Introduction - Web APIs have quickly become an important part of Web Infrastructure. However the + Web APIs have quickly become an important part of Web Infrastructure. However the amount of machine readable meta-data about the location and capabilities of these APIs - remains extremely limited. + 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 + 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 + The objective of the format defined in this document is to provide a lightweight means + for individuals and organizations 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 @@ -75,20 +75,20 @@ Table of Contents 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 defined content types [currently JSON and TXT]. A file + * Apis.* file, a file which contains API Meta Data information compatible with this + document and uses one of the defined content types [currently JSON, YAML 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 + * 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 from + The definitions of API Meta Data MUST be accessible by HTTP or HTTPS or Both 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 as determined by the content type under - a standard relative path on the server: "/apis.*", where * is determined by the + for information on Authoritative and Non-Authoritative definitions) as a resource of + Internet Media Type as determined by the content type 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.* @@ -111,13 +111,13 @@ Table of Contents 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 + 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 intended to be human readable and may be used by humans, it + While the format is intended 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. + systems may be part of search engines, testing frameworks or API using applications. In keeping with terminology from the robots.txt format they are referred to as robots from here onwards. @@ -125,7 +125,7 @@ Table of Contents 3.121 Authoritative - An entry in a apis.* file is AUTHORITATIVE for a given domain if the root domain of + 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 @@ -134,20 +134,20 @@ Table of Contents 3.2.3 Authority by Reference - For Discussion: 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 + For Discussion: 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 separate apis.* files for a - a specific API, priority on the validity of information should generally be resolved + In cases where a robot discovers more than one entry in separate 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 + * 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 @@ -160,64 +160,74 @@ Table of Contents 3.3. Formal Syntax -3.3.1. JSON Format +3.3.1. JSON or YAML 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 + This is a proposed specification for an apis.json or apis.yaml 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: + A file shall be in JSON or YAML format and contain the following elements: - * Name [Mandatory]: text string of human readable name for the collection of APIs - * Description [Mandatory]: text human readable description of the collection of APIs. - * Image [Optional]: Web URL leading to an image to be used to represent the collection of + * name [Mandatory]: text string of human readable name for the collection of APIs + * description [Mandatory]: text human readable description of the collection of APIs. + * type [Optional]: Type of collection (Index [of a single API], Collection [of multiple APIs], Blueprint [of a new API]). + * image [Optional]: Web URL leading to an image to be used to represent the collection of APIs defined in this file. - * Url [Mandatory]: Web URL indicating the location of the latest version of this file - * Tags (collection) Optional]: - this is a list of descriptive strings which identify the contents of the APIs.json file. Represented - as an array. - * Created [Mandatory]: date of creation of the file - * Modified [Mandatory]: date of last modification of the file + * url [Mandatory]: Web URL indicating the location of the latest version of this file + * tags (collection) Optional]: + this is a list of descriptive strings which identify the contents of the APIs.json file. Represented + as an array. + * created [Mandatory]: date of creation of the file + * modified [Mandatory]: date of last modification of the file * specificationVersion [Mandatory]: version of the APIs.json specification in use. - - * 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. - * Image [Optional]: URL of an image which can be used as an "icon" for the API if displayed by a + * 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. + * image [Optional]: 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. + * humanUrl: Web URL corresponding to human readable information about 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. - * Tags: (collection) [Optional]: this is a list of descriptive strings which identify the API. - as an array. + * version [Optional]: String representing the version number of the API this description refers to. + * tags: (collection) [Optional]: this is a list of descriptive strings which identify the API. + as an array. * properties (collection): - - type: please see reserved keywords below. - - url or value. + - name [Optional]: The display name of the property. + - type: please see reserved keywords below. + - mediaType [Optional]: IANA media type representing the property. + - url [Optional]: The URL for the property. * must be url or data + - data [Optional]: The data for the property. * must be url or data * contact (collection) - [Person or Organization - see below] - * Include (collection) [Optional] + * common (collection) [Optional]: a list of common properties for use across all APIs and tools + - name [Optional]: The display name of the property. + - type: please see reserved keywords below. + - mediaType [Optional]: IANA media type representing the property. + - url or value. + + * include (collection) [Optional] * Name [Mandatory]: name of the APIs.json file referenced. * Url [Mandatory]: Web URL of the file. - * Maintainers (collection) [VCARD] + * maintainers (collection) [VCARD] * [Person or Organization - see below] - The above elements determine the information to be provided (examples are provided lower down). In + The above elements determine the information to be provided (examples are provided lower down). In addition the format reserves keywords for types. These are listed in Section 6. The Person or Organization is defined as containing: - * FN [Optional]: String Value corresponding to the Full Nname name of the individual / organization. - * Email [Optional]: String Value corresponding to the email address of the individual / organization - * Url [Optional]: String Value corresponding to a web page about the individual individual / organization + * fn [Optional]: String Value corresponding to the Full Nname name of the individual / organization. + * email [Optional]: String Value corresponding to the email address of the individual / organization + * url [Optional]: String Value corresponding to a web page about the individual individual / organization * org [Optional]: String Value representing the name of the organization associated with the cCard. - * Adr [Optional]: String Value corresponding to the physical address of the individual / organization. - * Tel [Optional]: String Value corresponding to the phone number including country code of the individual / organization. - * X-Twitter [Optional]: String Value corresponding to the twitter username of the individual / organization (convention do + * adr [Optional]: String Value corresponding to the physical address of the individual / organization. + * tel [Optional]: String Value corresponding to the phone number including country code of the individual / organization. + * x-twitter [Optional]: String Value corresponding to the twitter username of the individual / organization (convention do not use the "@" symbol). Note - these are X- since this is the way they are / would be in vCard. - * X-Github [Optional]: String Value corresponding to the github username of the individual / organization. Note - these are X- since this is the way they are / would be in vCard. + * x-github [Optional]: String Value corresponding to the github username of the individual / organization. Note - these are X- since this is the way they are / would be in vCard. * photo [Optional]: URL corresponding to an image which could be used to represent the individual / organization. * vCard [Optional]: URL pointing to a vCard Objective RFC6350 @@ -243,28 +253,29 @@ Table of Contents If no cache-control directives are present robots should default to an expiry of 7 days. -3.5. Media Type +3.5. Media Type - It is intended that if there is sufficient traction, the media type "application/apis+json" will be + It is intended that if there is sufficient traction, the media type "application/apis+json" or "application/x-yaml" will be submitted to IANA as per RFC: http://tools.ietf.org/html/rfc4288 -3.6. JSON Schema +3.6. JSON Schema A JSON schema is under development for the format. -3.7. Well Known +3.7. Well Known - It is intended that if there is sufficient traction, the "well known" location "/apis.json" will be + It is intended that if there is sufficient traction, the "well known" location "/apis.json" or "/apis.yaml" will be submitted as per RFC: http://tools.ietf.org/html/rfc5785 -3.8. Link Relation +3.8. Link Relation - In order for a Web site to reference its API description, it is recommended that it includes a header or - in-line reference to the APIs.json resource using the api link relation, e.g.: + In order for a Web site to reference its API description, it is recommended that it includes a header or + in-line reference to the APIs.json resource using one of the api link relation, e.g.: * + * - It is intended that if there is sufficient traction, the link relation “api” will be + It is intended that if there is sufficient traction, the link relation “api” will be submitted to IANA as per RFC: http://tools.ietf.org/html/rfc5988 3.9. Extensions @@ -273,148 +284,163 @@ Table of Contents 4. Examples - Here is the api.json for API Evangelist: - - { - "name": "API Evangelist", - "description": "This is an inventory of APIs available as part of the API Evangelist network.", - "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", - "tags": [ - "application programming interface", - "API", - "News", - "Analysis" - ], - "created": "2014-04-07", - "modified": "2014-07-09", - "url": "http://apievangelist.com/apis.json", - "specificationVersion": "0.15", - "apis": [ - { - "name": "Analysis", - "description": "Provides access to blog posts and analysis across the API Evangelist network.", - "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", - "humanURL": "http://developer.apievangelist.com", - "baseURL": "http://api.apievangelist.com/definitions/Analysis", - "tags": [ - "blog", - "industry", - "analysis", - "new", - "API", - "Application Programming Interface" - ], - "properties": [ - { - "type": "X-signup", - "url": "https://apievangelist.3scale.net/" - }, - { - "type": "Swagger", - "url": "http://api.apievangelist.com/definitions/Analysis" - }, - { - "type": "X-blog", - "url": "http://developer.apievangelist.com/blog/" - }, - { - "type": "X-apicommonsmanifest", - "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json" - } - ], - "contact": [ - { - "FN": "API Evangliest", - "email": "info@apievangelist.com", - "X-twitter": "apievangelist" - } - ] - }, - { - "name": "APIs", - "description": "Provides access to APIs that are being tracked across the API Evangelist network.", - "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", - "humanURL": "http://developer.apievangelist.com", - "baseURL": "http://api.apievangelist.com/definitions/APIs", - "tags": [ - "application programming interface", - "API" - ], - "properties": [ - { - "type": "X-signup", - "url": "https://apievangelist.3scale.net/" - }, - { - "type": "Swagger", - "url": "http://api.apievangelist.com/definitions/APIs" - }, - { - "type": "X-blog", - "url": "http://developer.apievangelist.com/blog/" - }, - { - "type": "X-apicommonsmanifest", - "url": "https://raw.githubusercontent.com/kinlane/api-api/master/api-commons-manifest.json" - } - ], - "contact": [ - { - "FN": "API Evangliest", - "email": "info@apievangelist.com", - "X-twitter": "apievangelist" - } - ] - } - ], - "include": [ - { - "name": "API Evangelist - Products", - "url": "http://products.apievangelist.com/apis.json" - }, - { - "name": "API Evangelist - Screen Capture", - "url": "http://screen-capture.apievangelist.com/apis.json" - }, - { - "name": "API Evangelist - Image Manipulation", - "url": "http://image.manipulation.apievangelist.com/apis.json" - }, - { - "name": "API Evangelist - API Ideas", - "url": "http://ideas.apievangelist.com/apis.json" - }, - { - "name": "API Commons", - "url": "http://apicommons.org/apis.json" - } - ], - "maintainers": [ - { - "FN": "Kin", - "X-twitter": "apievangelist", - "email": "kin@email.com", - "vCard":"http://staging.apis.io/vCards/testVcard.vcf" - } - ] - } - + Here is an example api.json file: + + { + "name": "Example API", + "type": "Index", + "description": "This is an example APIs.json file, demonstrating what is possible with\nthe API discovery specification.", + "image": "https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg", + "tags": [ + "Application Programming Interface", + "API" + ], + "created": "2014-04-07", + "modified": "2020-09-03", + "url": "http://example.com/apis.json", + "specificationVersion": "0.16", + "apis": [ + { + "name": "Example API", + "description": "This provides details about a specific API, telling what is possible.", + "image": "https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg", + "humanURL": "http://example.com", + "baseURL": "http://api.example.com", + "tags": [ + "API", + "Application Programming Interface" + ], + "properties": [ + { + "type": "Documentation", + "url": "https://example.com/documentation" + }, + { + "type": "OpenAPI", + "url": "http://example.com/openapi.json" + }, + { + "type": "JSONSchema", + "url": "http://example.com/json-schema.json" + } + ], + "contact": [ + { + "FN": "APIs.json", + "email": "info@apisjson.org", + "X-twitter": "apisjson" + } + ] + } + ], + "common": [ + { + "type": "Signup", + "url": "https://example.com/signup" + }, + { + "type": "Authentication", + "url": "http://example.com/authentication" + }, + { + "type": "Login", + "url": "https://example.com/login" + }, + { + "type": "Blog", + "url": "http://example.com/blog" + }, + { + "type": "Pricing", + "url": "http://example.com/pricing" + } + ], + "include": [ + { + "name": "Another Example API", + "url": "http://example.com/apis.json" + } + ], + "maintainers": [ + { + "FN": "Kin Lane", + "X-twitter": "apievangelist", + "email": "info@apievangelist.com" + } + ] + } + + Here is an example api.yaml file: + + name: Example API + type: Index + description: This is an example APIs.json file, demonstrating what is possible with + the API discovery specification. + image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg + tags: + - Application Programming Interface + - API + created: '2014-04-07' + modified: '2020-09-03' + url: http://example.com/apis.json + specificationVersion: '0.16' + apis: + + - name: Example API + description: This provides details about a specific API, telling what is possible. + image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg + humanURL: http://example.com + baseURL: http://api.example.com + tags: + - API + - Application Programming Interface + + properties: + - type: Documentation + url: https://example.com/documentation + - type: OpenAPI + url: http://example.com/openapi.json + - type: JSONSchema + url: http://example.com/json-schema.json + + contact: + - FN: APIs.json + email: info@apisjson.org + X-twitter: apisjson + + common: + - type: Signup + url: https://example.com/signup + - type: Authentication + url: http://example.com/authentication + - type: Login + url: https://example.com/login + - type: Blog + url: http://example.com/blog + - type: Pricing + url: http://example.com/pricing + include: + - name: Another Example API + url: http://example.com/apis.json + maintainers: + - FN: Kin Lane + X-twitter: apievangelist + email: info@apievangelist.com 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. + 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. - All such visible endpoints should be secured in an appropriate manner. + 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 @@ -429,57 +455,73 @@ Table of Contents 8. Acknowledgements - The specification provided here was inspired by conversation in the API Community at events + 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. + Gluecon, Defrag and others. 9. Authors' Address - Kin Lane, + Kin Lane, API Evangelist http://www.apievangelist.com/ - email: + email: Steven Willmott - 3scale networks + 3scale networks http://www.3scale.net/ email: steve@3scale.net - Nicolas Grenie, - 3scale networks, - http://www.3scale.net/ - email: nicolas@3scale.net - - ----RESERVED WORDS -Reserved Words for APIs.json Specification +Reserved Words for APIs.json / APIS.yaml Specification * Version 1 -Definition Elements: +Definition Elements: * Name * HumanURL * BaseURL * Description * Image - * Version + * Version * Tags Properties Elements: * Swagger + * OpenAPI + * JSONSchema + * PostmanCollection + * AsyncAPI * RAML * Blueprint * WADL * WSDL - + + * Documentation + * Authentication + * Signup + * Login * TermsOfService * InterfaceLicense + * PrivacyPolicy + * Security + * SDKs * StatusPage * Pricing + * Rate Limits + * Blog + * BlogFeed * Forums + * Support + * ChangeLog + * RoadMap + * Contact + * ErrorCodes + * GitHubOrg + * GitHubRepo + * Twitter * AlertsTwitterHandle Contact Elements: @@ -488,13 +530,13 @@ Contact Elements: Maintainer Elements: - * name + * name * twitter - * github - * email - * url - * organizationName - * organizationUrl - * address - * phoneNumber - * image + * github + * email + * url + * organizationName + * organizationUrl + * address + * phoneNumber + * image