Network Working Group Brian Pawlowski Internet-Draft Network Appliance Scott Bradner Harvard University Allison Mankin USC/ISI February 2002 Advancement of Application Programming Interface specifications on the IETF Standards Track 1. Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC 2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html A revised version of this draft document will be submitted to the RFC editor as a BCP (Best Current Practice) documenting an IESG procedure for the Internet Community. Discussion and suggestions for improvement are requested. This document will expire before August, 2002. Distribution of this draft is unlimited. 2. Abstract The Internet Standards Process [RFC2026] requires that all IETF Standards Track specifications must have "multiple, independent, and interoperable implementations" before they can be advanced beyond Proposed Standard status. This document specifies the test which the Pawlowski [Page 1] Internet-Draft API Specification Advancement February 2002 IESG will use to determine if an Application Programming Interface (API) specification document meets these requirements. It also discusses the rationale for this process. 3. The Nature of the Problem The Internet Standards Process [RFC2026] requires that for a IETF specification to advance beyond the Proposed Standard level, at least two genetically unrelated implementations must be shown to interoperate correctly with all features and options. There are two distinct reasons for this requirement. The first reason is to verify that the text of the specification is adequately clear and accurate. This is demonstrated by showing that multiple implementation efforts have used the specification to achieved interoperable implementations. The second reason is to discourage excessive options and "feature creep". This is accomplished by requiring interoperable implementation of all features, including options. If an option is not included in at least two different interoperable implementations, it is safe to assume that it has not been deemed useful and must be removed before the specification can advance. In the case of a protocol specification which specifies the "bits on the wire" exchanged by executing state machines, the notion of "interoperability" is reasonably intuitive - the implementations must successfully "talk to each other", exchanging "bits on the wire", while exercising all features and options. In the case of a specification for an application programming interface (API), a security framework for example [RFC2743], exactly what constitutes "interoperation" is less obvious. This document specifies how the IESG has decided to judge "API specification interoperability" in the context of the IETF Standards Process. For the purposes of this document, APIs define a method of accessing services for callers in a generic fashion, supportable with a range of underlying mechanisms and technologies and hence allowing source-level portability of applications to different environments. An API specification defines services and primitives at a level independent of underlying mechanism and programming language environment, and is to be complemented by other, related specifications defining specific language bindings and token formats and protocols in support of the services provided by the API. The aim is to ensure that the dual goals of specification clarity and feature evaluation have been met using an interpretation of the concept of API specification interoperability that strikes a balance between testing complexity and practicality. 4. On The Nature of API specifications Compared to "state machine" protocols which focus on procedural specifications, an API specification describes a method of constructing and deconstructing data for transmission over-the-wire using a standard set of routines or programming interfaces such that interoperability is assured. One example of such an API would be a way allows a communicating application to authenticate the user associated with another application, to delegate rights to another application, and to apply security services such as confidentiality and integrity on a per-message basis while being sent from one network location to another - without regard to the specific security mechanism chosen. Pawlowski [Page 2] Internet-Draft API Specification Advancement February 2002 A central issue is that an API specification does not stand alone; it forms the access interface to the data underneath it. Without the data, an API provides structure but no content. Since implementations of APIs are by their nature standalone and do not interact with each other, the level of the interoperability called for in the IETF standards process cannot be simply determined by seeing that the implementations interact properly. 5. Discussion and Recommended Process In order to meet their obligations under the IETF Standards Process the IESG must be convinced that each API specification advanced to Draft Standard or Internet Standard status is clearly written, that there are the required multiple interoperable implementations, and that all options have been implemented. There may be multiple ways to achieve this goal; this memo documents the way that the IESG will use to determine if the requirements have been met. In the context of this memo, APIs are designed to uniformly construct data for exchange over a data network. An aim of any API definition should be that it should be specified in a way that can reliably construct data for transmission and receipt in the face of heterogeneous end points. Thus exchanging data constructed by an API should allow reliable interoperable exchange regardless of end points. In the same way, sequentially running different implementations of software that construct and deconstruct data using the API should produce the same results. Following these assumptions any recommendation for the advancement of a API specification must be accompanied by an implementation report, as is the case with all requests for the advancement of IETF specifications. The implementation report must include reports of tests performed between sets of points on a network with two or more implementations of the software. Each API specification suggested for advancement must have one or more advocates who can make a convincing argument that the API specification meets the multiple implementation and feature support requirements of the IETF Standards Process. The specific way to make the argument is left to the advocate, but will normally include reports that basic data exchange testing has been done. The API should be tested with at least two substantially different data to be exchanged (for example, in the case of a security API, it should be shown that the API correctly supports two different security mechanisms). Pawlowski [Page 3] Internet-Draft API Specification Advancement February 2002 The prime concern of the IESG will be that the underlying reasons for the interoperable implementations are met, i.e. that the text of the specification is clear and unambiguous, and that features of the specification which have not garnered support have been removed from the specification before the specification can be advanced on the standards track. If the API has options (it is defined as a set of procedures), all of the options (and procedures) must be tested in the same way. An implementation report is required for both the advancement from Proposed Standard to Draft Standard and from Draft Standard to Internet Standard. The implementation report for advancement from Draft Standard to Internet Standard can be an updated version of the one used for the advancement from Proposed Standard to Draft Standard. Pawlowski [Page 4] Internet-Draft API Specification Advancement February 2002 The implementation report must include the reasons why the IESG should believe that there are multiple implementations of the API specification in question and that the all of the API routines in the specification to be advanced are supported in more than one implementation. But note that the prime concern of the IESG will be that the underlying reasons for the interoperable implementations are met, i.e., that the text of the specification is clear and unambiguous, and that features of the specification which have not garnered support have been removed. The implementation report will be placed on the IETF web page along with the other pre-advancement implementation reports and will be specifically referred to in the IETF Last-Call. As with all such implementation reports, the determination of adequacy is made by the IESG upon recommendation by the Area Director(s) of the relevant IETF Area. This determination of adequacy can be challenged during the Last-Call period. 6. Security Considerations Some may view this policy as possibly leading to a reduction in the level of confidence people can have in API specifications, but the IESG feels that it will adequately ensure a reasonable evaluation of the level of clarity and ensure that unused options can be identified and removed before the advancement of a specification. Good, clearly written API specifications can be of great assistance in the deployment of interoperable implementations on the Internet and likely assist in the reduction of some types of security threats through standardize data construction. 7. Acknowledgements The basic format and some of the text for this memo came from [RFC2438], "Advancement of MIB specifications on the IETF Standards Track", which provides similar guidance for the advancement of MIBs and [Bradner] "Advancement of Metrics specifications on the IETF Standards Track" providing guidance on advancement of metrics. 8. References [RFC2026] "The Internet Standards Process -- Revision 3", Bradner, October 1996 [RFC2438] "Advancement of MIB specifications on the IETF Standards Track", O'Dell, Alvestrand, Wijnen, & Bradner, October 1998 [Bradner] "Advancement of Metrics specifications on the IETF Standards Track", Bradner, Mankin, Paxson, draft-bradner-metricstest-00.txt, February 2000 [RFC2743] "Generic Security Service Application Program Interface Version 2, Update 1", Linn, January 2000 9. Author's Addresses Pawlowski [Page 5] Internet-Draft API Specification Advancement February 2002 Brian Pawlowski Network Appliance 495 East Java Drive Sunnyvale, CA 94089 USA Email: beepy@netapp.com Phone: +1-408-822-6796 Scott Bradner Harvard University 29 Oxford St. Cambridge MA 02138 Email: sob@harvard.edu Phone: +1-617-495-3864 Allison Mankin USC/ISI 4350 N. Fairfax Drive, Suite 620 Arlington VA 22203 Email: mankin@isi.edu Phone: +1-703-812-3706 Pawlowski [Page 6]