]> Microsoft

darrel.miller@microsoft.com

General Internet Engineering Task Force API Http OpenAPI 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 The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

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. 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 person who consents to 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.

Schema

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 publisher property that has a value described by the publisher and MUST contain a JSON object that contains of zero or more mappings from a string key to Api Dependency objects. The API Manifest object MUST contain an applicationName string property to uniquely identify the application to users of the API Manifest.

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.

API Dependency Object Each API dependency object represents an 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 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 authorizationRequirements property contains the requirements for the target application to authorize a call to the HTTP API. The requests property contains an array of requestInfo objects.

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 access property is a JSON object that has the structure and semantics of the authorization_details defined in that are required to perform the complete set of requests defined in the Api Dependency . The Api Manifest does not attempt to correlate which permission is required for a specific request. It is assumed that the application must be granted the complete set of permissions in order to perform its function.

Request Info Object Each Request Info object contains a uriTemplate and a corresponding HTTP method. The values are used to identify an operation defined in the API description referenced in the Api Dependency. If the API Dependency 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. 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:

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.

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 when, and only when, they appear in all capitals, as shown here.

Security Considerations TODO Security

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 . 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: Person & email address to contact for further information: See Authors' Addresses section. Intended usage: COMMON Restrictions on usage: n/a Author: See Authors' Addresses section. Change controller: Internet Engineering Task Force (mailto:iesg@ietf.org).

Normative References A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document specifies a new parameter that is used to carry fine-grained authorization data in OAuth messages. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Acknowledgments TODO acknowledge.

Appendix

Example for Microsoft Graph API