idnits 2.17.1 draft-pawlowski-apitest-01.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 2) being 73 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 6 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC2026]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 60 has weird spacing: '...tically unrel...' == Line 61 has weird spacing: '...rrectly with ...' == Line 144 has weird spacing: '...nstruct and d...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 2002) is 7832 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2744' is defined on line 235, but no explicit reference was found in the text == Unused Reference: 'RFC2853' is defined on line 238, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-bradner-metricstest-00 -- Possible downref: Normative reference to a draft: ref. 'Bradner' ** Obsolete normative reference: RFC 2853 (Obsoleted by RFC 5653) Summary: 9 errors (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Brian Pawlowski 3 Internet-Draft Network Appliance 4 Scott Bradner 5 Harvard University 6 Allison Mankin 7 USC/ISI 8 November 2002 10 Advancement of Application Programming Interface specifications 11 on the IETF Standards Track 13 15 1. Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC 2026. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet- Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html 36 A revised version of this draft document will be submitted to the RFC 37 editor as a BCP (Best Current Practice) documenting an IESG procedure 38 for the Internet Community. 40 Discussion and suggestions for improvement are requested. This 41 document will expire before August, 2002. Distribution of this draft 42 is unlimited. 44 2. Abstract 46 The Internet Standards Process [RFC2026] requires that all IETF 47 Standards Track specifications must have "multiple, independent, and 48 interoperable implementations" before they can be advanced beyond 49 Proposed Standard status. This document specifies the test which the 51 =0C 52 IESG will use to determine if an Application Programming Interface 53 (API) specification document meets these requirements. It also 54 discusses the rationale for this process. 56 3. The Nature of the Problem 58 The Internet Standards Process [RFC2026] requires that for a IETF 59 specification to advance beyond the Proposed Standard level, at least 60 two genetically unrelated implementations must be shown to 61 interoperate correctly with all features and options. There are two 62 distinct reasons for this requirement. 64 The first reason is to verify that the text of the specification is 65 adequately clear and accurate. This is demonstrated by showing that 66 multiple implementation efforts have used the specification to 67 achieved interoperable implementations. 69 The second reason is to discourage excessive options and "feature 70 creep". This is accomplished by requiring interoperable 71 implementation of all features, including options. If an option is 72 not included in at least two different interoperable implementations, 73 it is safe to assume that it has not been deemed useful and must be 74 removed before the specification can advance. 76 In the case of a protocol specification which specifies the "bits on 77 the wire" exchanged by executing state machines, the notion of 78 "interoperability" is reasonably intuitive - the implementations must 79 successfully "talk to each other", exchanging "bits on the wire", 80 while exercising all features and options. 82 In the case of a specification for an application programming 83 interface (API), a security framework for example [RFC 2744 and 84 RFC2853] describing language bindings for [RFC2743], exactly what 85 constitutes "interoperation" is less obvious. This document 86 specifies how the IESG has decided to judge "API specification 87 interoperability" in the context of the IETF Standards Process. 89 For the purposes of this document, APIs define a method of accessing 90 services for callers in a generic fashion, supportable with a range 91 of underlying mechanisms and technologies and hence allowing 92 source-level portability of applications to different environments. 93 An API specification defines services and primitives at a level 94 independent of underlying mechanism and programming language 95 environment, and is to be complemented by other, related 96 specifications defining specific language bindings and token formats 97 and protocols in support of the services provided by the API. 99 The aim is to ensure that the dual goals of specification clarity and 100 feature evaluation have been met using an interpretation of the 101 concept of API specification interoperability that strikes a 102 balance between testing complexity and practicality. 104 4. On The Nature of API specifications 106 Compared to "state machine" protocols which focus on procedural 107 specifications, an API specification describes a method of 108 constructing and deconstructing data for transmission over-the-wire 109 using a standard set of routines or programming interfaces such that 110 interoperability is assured. One example of such an API would be a 111 way allows a communicating application to authenticate the user 112 associated with another application, to delegate rights to another 113 application, and to apply security services such as confidentiality 114 and integrity on a per-message basis while being sent from one 115 network location to another - without regard to the specific security 116 mechanism chosen. 118 =0C 119 A central issue is that an API specification does not stand alone; it 120 forms the access interface to the data underneath it. Without the 121 data, an API provides structure but no content. Since 122 implementations of APIs are by their nature standalone and do not 123 interact with each other, the level of the interoperability called 124 for in the IETF standards process cannot be simply determined by 125 seeing that the implementations interact properly. 127 5. Discussion and Recommended Process 129 In order to meet their obligations under the IETF Standards Process 130 the IESG must be convinced that each API specification advanced to 131 Draft Standard or Internet Standard status is clearly written, that 132 there are the required multiple interoperable implementations, and 133 that all options have been implemented. There may be multiple ways 134 to achieve this goal; this memo documents the way that the IESG will 135 use to determine if the requirements have been met. 137 In the context of this memo, APIs are designed to uniformly construct 138 data for exchange over a data network. An aim of any API definition 139 should be that it should be specified in a way that can reliably 140 construct data for transmission and receipt in the face of 141 heterogeneous end points. Thus exchanging data constructed by an API 142 should allow reliable interoperable exchange regardless of end 143 points. In the same way, sequentially running different 144 implementations of software that construct and deconstruct data 145 using the API should produce the same results. 147 Following these assumptions any recommendation for the advancement of 148 a API specification must be accompanied by an implementation report, 149 as is the case with all requests for the advancement of IETF 150 specifications. The implementation report must include reports of 151 tests performed between sets of points on a network with two or more 152 implementations of the software. Each API specification suggested 153 for advancement must have one or more advocates who can make a 154 convincing argument that the API specification meets the multiple 155 implementation and feature support requirements of the IETF Standards 156 Process. The specific way to make the argument is left to the 157 advocate, but will normally include reports that basic data exchange 158 testing has been done. The API should be tested with at least two 159 substantially different data to be exchanged (for example, in the 160 case of a security API, it should be shown that the API correctly 161 supports two different security mechanisms). 163 =0C 164 The prime concern of the IESG will be that the underlying reasons for 165 the interoperable implementations are met, i.e. that the text of the 166 specification is clear and unambiguous, and that features of the 167 specification which have not garnered support have been removed from 168 the specification before the specification can be advanced on the 169 standards track. If the API has options (it is defined as a set of 170 procedures), all of the options (and procedures) must be tested in 171 the same way. 173 An implementation report is required for both the advancement from 174 Proposed Standard to Draft Standard and from Draft Standard to 175 Internet Standard. The implementation report for advancement from 176 Draft Standard to Internet Standard can be an updated version of the 177 one used for the advancement from Proposed Standard to Draft 178 Standard. 180 =0C 181 The implementation report must include the reasons why the IESG 182 should believe that there are multiple implementations of the API 183 specification in question and that the all of the API routines in the 184 specification to be advanced are supported in more than one 185 implementation. But note that the prime concern of the IESG will be 186 that the underlying reasons for the interoperable implementations are 187 met, i.e., that the text of the specification is clear and 188 unambiguous, and that features of the specification which have not 189 garnered support have been removed. 191 The implementation report will be placed on the IETF web page along 192 with the other pre-advancement implementation reports and will be 193 specifically referred to in the IETF Last-Call. As with all such 194 implementation reports, the determination of adequacy is made by the 195 IESG upon recommendation by the Area Director(s) of the relevant IETF 196 Area. This determination of adequacy can be challenged during the 197 Last-Call period. 199 6. Security Considerations 201 Some may view this policy as possibly leading to a reduction in the 202 level of confidence people can have in API specifications, but 203 the IESG feels that it will adequately ensure a reasonable evaluation 204 of the level of clarity and ensure that unused options can be 205 identified and removed before the advancement of a specification. 207 Good, clearly written API specifications can be of great assistance 208 in the deployment of interoperable implementations on the Internet 209 and likely assist in the reduction of some types of security threats 210 through standardize data construction. 212 7. Acknowledgements 214 The basic format and some of the text for this memo came from 215 [RFC2438], "Advancement of MIB specifications on the IETF Standards 216 Track", which provides similar guidance for the advancement of MIBs 217 and [Bradner] "Advancement of Metrics specifications on the IETF 218 Standards Track" providing guidance on advancement of metrics. 220 8. References 222 [RFC2026] "The Internet Standards Process -- Revision 3", Bradner, 223 October 1996 225 [RFC2438] "Advancement of MIB specifications on the IETF Standards 226 Track", O'Dell, Alvestrand, Wijnen, & Bradner, October 1998 228 [Bradner] "Advancement of Metrics specifications on the IETF 229 Standards Track", Bradner, Mankin, Paxson, 230 draft-bradner-metricstest-00.txt, February 2000 232 [RFC2743] "Generic Security Service Application Program Interface 233 Version 2, Update 1", Linn, January 2000 235 [RFC2744] "Generic Security Service API Version 2 : C-bindings", 236 Wray, January 2000 238 [RFC2853] "Generic Security Service API Version 2 : Java Bindings", 239 Kabat, Upadhyay, June 2000 241 9. Author's Addresses 243 =0C 244 Brian Pawlowski 245 Network Appliance 246 495 East Java Drive 247 Sunnyvale, CA 94089 248 USA 250 Email: beepy@netapp.com 251 Phone: +1-408-822-6796 253 Scott Bradner 254 Harvard University 255 29 Oxford St. 256 Cambridge MA 02138 258 Email: sob@harvard.edu 259 Phone: +1-617-495-3864 261 Allison Mankin 262 USC/ISI 263 4350 N. Fairfax Drive, Suite 620 264 Arlington VA 22203 266 Email: mankin@isi.edu 267 Phone: +1-703-812-3706