Skip to main content

API Manifest
draft-miller-api-manifest-00

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]