Internet-Draft API Manifest July 2023
Miller Expires 25 January 2024 [Page]
Workgroup:
Internet Engineering Task Force
Internet-Draft:
draft-miller-api-manifest-01
Published:
Intended Status:
Informational
Expires:
Author:
D. Miller
Microsoft

API Manifest

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.

▲

Table of Contents

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.

An API manifest such as described in this document could enable a number of scenarios:

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.

2. Schema

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 publisher 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 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.

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 access property is a JSON object that has the structure and semantics of the authorization_details defined in [RAR] that are 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 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 [URITEMPLATE] 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.

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:

{
    "publisher": {
        "name": "Alice",
        "contactEmail": "alice@example.org"
    },
    "apiDependencies": {
        "example": {
            "apiDescriptionUrl": "https://example.org/openapi.json",
            "apiDescriptionVersion": "1.2",
            "apiDeploymentBaseUrl": "https://example.org/",
            "authorizationRequirements": {
                "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.

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 [JSON].

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.

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

[JSON]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, , <https://www.rfc-editor.org/rfc/rfc7159>.
[RAR]
Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, , <https://www.rfc-editor.org/rfc/rfc9396>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <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, , <https://www.rfc-editor.org/rfc/rfc8174>.
[URITEMPLATE]
Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, , <https://www.rfc-editor.org/rfc/rfc6570>.

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/",
            "authorizationRequirements": {
                "clientIdentifier": "some-uuid-here",
                "access": [
                    {
                        "type": "openid",
                        "claims": {
                            "scp": {
                                "essential": true,
                                "values": [
                                    "User.Read",
                                    "Mail.ReadWrite.All"
                                ]
                            }
                        }
                    },
                    {
                        "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