API Manifest
draft-miller-api-manifest-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
---|---|---|---|
Author | Darrel Miller | ||
Last updated | 2023-07-24 | ||
RFC stream | (None) | ||
Formats | |||
Stream | Stream state | (No stream defined) | |
Consensus boilerplate | Unknown | ||
RFC Editor Note | (None) | ||
IESG | IESG state | I-D Exists | |
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-miller-api-manifest-00
Internet Engineering Task Force D. Miller Internet-Draft Microsoft Intended status: Standards Track 24 July 2023 Expires: 25 January 2024 API Manifest draft-miller-api-manifest-00 Abstract This document defines an "api manifest" as a way to declare the dependencies that an application has on HTTP APIs. It contains characteristics of those dependencies including links to API descriptions, specifics of the types of HTTP API requests made by the application and related authorization information. About This Document This note is to be removed before publishing as an RFC. The latest revision of this draft can be found at https://darrelmiller.github.io/api-manifest/draft-miller-api- manifest.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-miller-api-manifest/. Source for this draft and an issue tracker can be found at https://github.com/darrelmiller/api-manifest. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 25 January 2024. Miller Expires 25 January 2024 [Page 1] Internet-Draft API Manifest July 2023 Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Api Manifest . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Publisher Object . . . . . . . . . . . . . . . . . . . . 4 2.3. API Dependency Object . . . . . . . . . . . . . . . . . . 4 2.4. Authorization Requirements Object . . . . . . . . . . . . 4 2.5. Request Info Object . . . . . . . . . . . . . . . . . . . 5 2.6. Extensibility . . . . . . . . . . . . . . . . . . . . . . 7 3. Conventions and Definitions . . . . . . . . . . . . . . . . . 8 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. Normative References . . . . . . . . . . . . . . . . . . . . 9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Example for Microsoft Graph API . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction Applications frequently rely on HTTP APIs to provide functionality to users. Currently, there are limited options for developers to be able to describe those dependencies and options that do exist do not have sufficiently detailed information to enable some of the desired scenarios. By contrast, there does exist declarative, machine readable files, that describe the dependencies that applications have on code libraries and packages. These files have enabled an ecosystem of tooling related to checking, adding, updating and reporting on dependencies. This specification defines a machine processable format to enable a programming language agnostic tooling ecosystem be built around the dependencies applications have on HTTP APIs. Miller Expires 25 January 2024 [Page 2] Internet-Draft API Manifest July 2023 An API manifest such as described in this document could enable a number of scenarios: * generate a minimal set of client code that can be used to access the specified resources * define API subsets for API gateways * identify the scopes or roles that an application must be granted to be able to access those resources * use as Signed Statement in Trustworthy and Transparent Digital Supply Chains * perform dependency checks for updates to APIs in a similar way Dependabot tooling does for package dependencies * provide security alerts for APIs that have announced discovered vulnerabilities * describe the capabilities of a skill/plugin for a chat-based system It is common for the the person who consents an application to be used, and therefore access data and functionality of HTTP APIs, not be capable of reviewing application source code to understand the details of what an application does. The API manifest can be used to create admin friendly descriptions of application capabilities to simplify the process of application consent. There are no guarantees that an API manifest accurately describes that capabilities and dependencies of an application. There remains an element of trust. It is not in itself a security artifact. However, it can play an role in enabling tooling as part of a secure supply chain. By creating an API manifest format independent of the application programming language tooling that consumes the API manifest can be created in any programming language. Language specific tooling could be created to generate API manifests by introspecting application code. Tooling could be created to produce API manifests to support design first methodologies, or integration centric scenarios. 2. Schema Miller Expires 25 January 2024 [Page 3] Internet-Draft API Manifest July 2023 2.1. Api Manifest The Api Manifest document contains information about an application that consumes HTTP APIs. The canonical model for an API Manifest document is a JSON object. When serialized as JSON it can be identified by the application/api-manifest media type. An API manifest document SHOULD contain a appPublisher property that has a value described by the publisher Section 2.2 and MUST contain a JSON object that contains of zero or more mappings from a string key to Api Dependency Section 2.3 objects. The API Manifest object MUST contain an applicationName string property to uniquely identify the application to users of the API Manifest. 2.2. Publisher Object The publisher object MUST contain a name property that is a JSON string. This string contains a value representing the organization or individual responsible for the application that this api manifest belongs to. The contactEmail property MUST provide an email address to communicate information to the publisher of the application being described. 2.3. API Dependency Object Each API dependency object represents a HTTP API that the target application consumes. The API dependency object MAY contain a apiDescriptionUrl that references an API description document such as an OpenAPI (https://spec.openapis.org/oas/latest.html) description. The apiDescriptionVersion member can contain the version of the API Description used by the application. This member enables tooling to detect if the referenced API desription is updated. The auth property contains the requirements for the target application to authorize a call to the HTTP API. The requests property contains a array of requestInfo objects. 2.4. Authorization Requirements Object The Authorization Requirements object contains information that is required to authorize the application to perform the requests listed in the Api Dependency requests property. The clientId property is a JSON string value used to identify the application to an OAuth2 authorization server for APIs that use OAuth2 for authorization. The permissions property is a JSON object that map a set of security schemes to an array of permission strings required to perform the complete set of requests defined in the Api Dependency Section 2.3. The Api Manifest does not attempt to correlate which permission is required for a specific request. It is assumed that the application Miller Expires 25 January 2024 [Page 4] Internet-Draft API Manifest July 2023 must be granted the complete set of permissions in order to perform its function. 2.5. Request Info Object Each Request Info object contains a uriTemplate [RFC6570] and a corresponding HTTP method. The values are used to identify an operation defined in the API description referenced in the Api DependencySection 2.3. If the API DependencySection 2.3 contains a apiDeploymentBaseUrl then uriTemplate values that resolve to a relative reference MUST be relative to the apiDeploymentBaseUrl. The dataClassification property is a list of URIs used to indicate privacy classifications of the data being transmitted via the HTTP request. Miller Expires 25 January 2024 [Page 5] Internet-Draft API Manifest July 2023 apiManifest = { applicationName: tstr ? publisher: publisher apiDependencies : {* tstr => apiDependency} extensibility } ; Identification of the application developer / organization publisher = { name: tstr contactEmail: tstr } ; Declaration of application dependencies on HTTP API apiDependency = { ? apiDescriptionUrl: tstr ? apiDescriptionVersion: tstr ? apiDeploymentBaseUrl: tstr authorizationRequirements: authorizationRequirements requests: [+ requestInfo] extensibility } ; Permissions required by client application for the described dependency authorizationRequirements = { ? clientIdentifier: tstr ? access: [+accessRequest] | [+tstr] } extensibility = ( ? extensions => {* tstr => any } ) accessRequest = { type : tstr ; * tstr => any; } ; Details of a resource request requestInfo = { method: tstr uriTemplate: tstr ? dataClassification: [* tstr] } Example: Miller Expires 25 January 2024 [Page 6] Internet-Draft API Manifest July 2023 { "publisher": { "name": "Alice", "contactEmail": "alice@example.org" }, "apiDependencies": { "example": { "apiDescriptionUrl": "https://example.org/openapi.json", "apiDescriptionVersion": "1.2", "apiDeploymentBaseUrl": "https://example.org/", "auth": { "clientIdentifier": "some-uuid-here", "access": [ { "type": "delegated", "actions": [ "resourceA.ReadWrite", "resourceB.ReadWrite" ] }, { "type": "application", "actions": [ "resourceB.Read" ] } ] }, "requests": [ { "method": "GET", "uriTemplate": "/api/resourceA" }, { "method": "GET", "uriTemplate": "/api/resourceB" } ] } } } 2.6. Extensibility The API Manifest object and API Dependency object can be extended with additional properties. The extensions member is a map of properties whose values can be any valid JSON member. Miller Expires 25 January 2024 [Page 7] Internet-Draft API Manifest July 2023 3. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 4. Security Considerations TODO Security 5. IANA Considerations This document document registers the application/api-manifest media type. Type name: application Subtype name: api-manifest Required parameters: n/a Optional parameters: n/a Encoding considerations: Encoding considerations are identical to those specified for the "application/json" media type. See [RFC7159]. Security considerations: TBD. Interoperability considerations: TBD. Published specification: This document is the specification for this media type. Applications that use this media type: Additional information: Magic number(s): n/a File extension(s): TBD Macintosh file type code(s): n/a Person & email address to contact for further information: See Authors' Addresses section. Miller Expires 25 January 2024 [Page 8] Internet-Draft API Manifest July 2023 Intended usage: COMMON Restrictions on usage: n/a Author: See Authors' Addresses section. Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org). 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. Acknowledgments TODO acknowledge. Appendix Example for Microsoft Graph API { "publisher": { "name": "Alice", "contactEmail": "alice@example.org" }, "apiDependencies": { "graph": { "apiDescripionUrl": "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml", "apiDeploymentBaseUrl": "https://graph.microsoft.com/v1.0/", "auth": { "clientIdentifier": "some-uuid-here", "access": [ { "type": "openid", "claims": { "scp": { "essential": true, "values": [ "User.Read", "Mail.ReadWrite.All" Miller Expires 25 January 2024 [Page 9] Internet-Draft API Manifest July 2023 ] } } }, { "type": "openid", "claims": { "roles": { "essential": true, "values": [ "User.Read.All" ] } } } ] }, "requests": [ { "method": "GET", "uriTemplate": "me" }, { "method": "GET", "uriTemplate": "users/{userId}/messages" }, { "method": "GET", "uriTemplate": "users" } ] } } } Author's Address Darrel Miller Microsoft Email: darrel.miller@microsoft.com Miller Expires 25 January 2024 [Page 10]