[Search] [txt|pdfized|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]
Versions: 00 01                                                         
Network Working Group                                    Brian Pawlowski
Internet-Draft                                         Network Appliance
                                                           Scott Bradner
                                                      Harvard University
                                                          Allison Mankin
                                                                 USC/ISI
                                                           November 2002

   Advancement of Application Programming Interface specifications
                     on the IETF Standards Track

                   <draft-pawlowski-apitest-01.txt>

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]


=0C
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 [RFC 2744 and
   RFC2853] describing language bindings for [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]


=0C
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]


=0C
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]


=0C
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

   [RFC2744] "Generic Security Service API Version 2 : C-bindings",
   Wray, January 2000

   [RFC2853] "Generic Security Service API Version 2 : Java Bindings",
   Kabat, Upadhyay, June 2000

9. Author's Addresses


Pawlowski                                                       [Page 5]


=0C
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]