Building Protocols with HTTP
draft-ietf-httpbis-bcp56bis-15

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up. Changes are expected over time.

This version is dated 1 November 2019.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP, which is indicated in the document header. This is appropriate since it is a revision of a BCP. It is indicated in the header.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

This document updates advice to applications on how to use HTTP as a substrate for defining APIs. The previous guidance was from 2002, so this document does a lot to incorporate our learnings over the past 20 years.

Working Group Summary:

This document has been in the working group for quite a while now, as it was held for submission alongside the new HTTP core document revision. In general, there is good consensus. The one discussion point that arose in the WGLC which had a bit rougher consensus was about the level of normative requirement required for two issues: specifically, if use of HTTPS (HTTP with TLS) is RECOMMENDED or a MUST; and whether the use of HTTPS is a MUST for all authentication types. Some WG members do not want to make this more strict, since not all use cases for HTTP need or can use TLS; others believe that the use case addressed by this document (HTTP APIs over the Internet) is specific enough that the security requirement is appropriate.

Document Quality:

The document is well-written and carefully reviewed.

Personnel:

Shepherd: Tommy Pauly
Responsible AD: Francesca Palombini

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

I've review the document and find it ready for publication.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No concerns.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

The issue described above, regarding requirement of HTTPS, may be useful to have input from the security area on.

(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The one area I'd like to see discussed is the point about requiring HTTPS.

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

No IPR disclosures. All authors confirmed.

(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No IPR disclosures.

(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

The WG consensus seems strong, with many reviewers over a long period of time. The only disagreement outstanding is the point that has been raised earlier.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No appeals.

(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Only one nit:

  -- The draft header indicates that this document obsoletes RFC3205, but the
    abstract doesn't seem to mention this, which it should.

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

No formal review applicable.

(13) Have all references within this document been identified as either normative or informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

No.

(15) Are there downward normative references references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

Yes, it will obsolete RFC3205. This may be good to note in the abstract, which it does not currently. However, this RFC is quite old, so I'll leave it up to AD advice.

(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

No IANA Considerations.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No IANA Considerations.

(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

Not applicable.

(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

Not applicable.

[Ballot comment]
Nice work once again.

Questions (1) and (7) of the shepherd writeup weren't properly answered.

IMHO, I suggest dropping Appendix A.  Indicating (as you have) that this document replaces RFC 3205 is sufficient.

[Ballot comment]
Questions (1) and (7) of the shepherd writeup weren't properly answered.

IMHO, I suggest dropping Appendix A.  Indicating (as you have) that this document replaces RFC 3205 is sufficient.

[Ballot comment]
Thank you for the work put into this document, which is also easy and interesting to read.

Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education).

Special thanks to Tommy Pauly for his shepherd's write-up notably about the WG consensus.

I hope that this helps to improve the document,

Regards,

-éric

-- Section 2 --
I am puzzled by the wording " The requirements in this document" in this BCP... Should it rather be "The applicability of this document..." ?

The following bullet list is unclear whether it is a "OR" or a "AND".

-- Section 3.2 --
s/Another common practice/Another common mistake/ ?

Some examples would be welcome as well.

-- Section 4.4.2 --
Isn't the reference to RFC 7258 redundant in ""https" is RECOMMENDED to provide authentication, integrity and confidentiality, as well as mitigate pervasive monitoring attacks [RFC7258]." ?

-- Section 4.5 --
In "they are required to be registered" should normative "REQUIRED" be used ?

Also, possibly naively, surprised by the absence of the "POST" method in the list of detailed methods.

[Ballot comment]
Thanks to Tommy for the shepherd writeup, which was very nice except
that it only answered one of the three parts of question (1).

Thanks once again to the editors and WG for another very well-written
document! 

Thanks as well to Joe Salowey for the secdir review, and to the authors
for the discussion and updates in response to it.

I made a github pull request with a few editorial suggestions:
https://github.com/httpwg/http-extensions/pull/1616

Section 3.2

  As explained in [RFC8820], such "squatting" on a part of the URL

Are there toolchain issues that prevent BCP190 from being the reference
here or is there some other reason to prefer the RFC form of the
reference?

Section 4.3

It seems somewhat surprising that the things we say about client
behavior are basically unrelated to the areas where we ask for server
behaviors to be specified.  Is there anything useful to say about, e.g.,
how the client uses media types, handles header fields, and processes
link relationships (even if [FETCH] would also say such things)?

Section 4.4.2

  Applications that use HTTP will typically employ the "http" and/or
  "https" URI schemes. "https" is RECOMMENDED to provide
  authentication, integrity and confidentiality, as well as mitigate
  pervasive monitoring attacks [RFC7258].

It seems clear to me that use of "https" is both IETF current practice
and a general best practice.  I see the shepherd writeup's mention of
the extensive WG discussions on this guidance (regarding "RECOMMENDED"
vs "MUST"), and posit that the lack of a clear definition of what BCP 14
keywords mean in a BCP-status document (and perhaps some lack of clarity
as to what the scope of applicability of this document is) underlie much
of the controversy.  (We saw a similar controversy in what became RFC
8996 (part of BCP 195) and its various "MUST NOT"s.) In light of the
extensive WG discussion that already occurred, I do not see reason to
ballot DISCUSS on this topic, but do ask if avoiding BCP 14 keywords
entirely was considered, along the lines of:

% The use of TLS, i.e., the "https" URI scheme, is the best current
% practice, since it provides (source) authentication, integrity and
% confidentiality, as well as mitigation against pervasive monitoring
% attacks [RFC7258].

  *  The resources identified by the new scheme will still be available
      using "http" and/or "https" URLs.  [...]

Is this availability guaranteed, or just a common risk ("likely")?  I
could imagine a custom HTTP implementation that only allows requests
using a single (custom) scheme, though admittedly mostly just as a
thought experiment and not something practical.

Section 4.6.1

                                                        An application
  using HTTP should specify if any request header fields that it
  defines need to be modified or removed upon a redirect; however, this
  behaviour cannot be relied upon, since a generic client (like a
  browser) will be unaware of such requirements.

Should we encourage the application designer to use "fail safe"
semantics for such request header fields in light of the non-guarantee
that application-specific requirements will be heeded?  (Possibly in a
later section more focused on header fields or application state rather
than here.)

Section 4.9.1

  It is not necessary to add the public response directive
  ([I-D.ietf-httpbis-cache], Section 5.2.2.9) to cache most responses;
  it is only necessary when it's desirable to store an authenticated
  response.

This seems to be a slightly different definition than the referenced
document uses.  I am not entirely sure whether the divergence is
actually problematic, though.

Section 4.12

  Applications can use HTTP authentication Section 11 of
  [I-D.ietf-httpbis-semantics] to identify clients.  As per [RFC7617],
  the Basic authentication scheme is not suitable for protecting
  sensitive or valuable information unless the channel is secure (e.g.,
  using the "HTTPS" URI scheme).  Likewise, [RFC7616] requires the
  Digest authentication scheme to be used over a secure channel.

I see that this text has already been subject to quite a bit of
discussion, but RFC 7616 doesn't "require" this; it says that "it SHOULD
be over a secure channel like HTTPS".  If pressed to suggest an
alternate phrasing, I would offer "[RFC7616] expects the Digest
authentication scheme to be used over a secure channel", but I am not
specifically promoting that phrasing.

  With HTTPS, clients might also be authenticated using certificates
  [RFC5246].

  When used, it is important to carefully specify the scoping and use
  of authentication; if the application exposes sensitive data or
  capabilities (e.g., by acting as an ambient authority), exploits are
  possible.  Mitigations include using a request-specific token to
  assure the intent of the client.

To mention client certificate authentication and scoping of
authentication in such close proximity but not discuss the well-known
pitfalls of TLS client certificate authentication feels like it's
leaving a big gap open.

I think we want to add something roughly like:

% TLS client certificate authentication is intrinsically scoped to the
% underlying transport connection.  On such an authenticated connection,
% a client has no way of knowing whether the authenticated status was
% used in preparing the response (though "Vary: *" can provide a partial
% indication), and the only way to obtain a specifically unauthenticated
% response is to open a new connection.  Applications should consider
% whether or not client certificate authentication is appropriate for
% their needs and expected use patterns.  TLS Exported authenticators
% [I-D.ietf-tls-exported-authenticator] are an attempt to remove some of
% these limitations while retaining the convenience and other advantages
% of client certificate authentication.

(The last sentence is optional, of course.)

Section 6

Do we want to incorporate by reference the security considerations of
any other documents?  -semantics, -cache, and RFC 8288, perhaps?
("Application protocols using HTTP are subject to the security
considerations of HTTP itself and any extensions used;
[I-D.ietf-httpbis-semantics], [I-D.ietf-httpbis-cache], and [RFC8288]
are some often-relevant references.")
If not, there might be a few things worth mentioning as standalone,
e.g., risk of infinite redirect loops and the scope of issues possible when
Vary: isn't used.

The potential for skew between HTTP caching and (distinct) application
protocol lifetime values discussed in §4.9.3 is a likely source of
security issues, so that section might merit a mention in this listing.

Section 7.1

It's not entirely clear to me that RFC 7301 needs to be listed as
normative; we mention ALPN only in the context of (paraphrasing)
"applications using HTTP ALPN values are subject to these requirements".

Section 7.2

We reference httpbis-cache in a number of places, and the sentiment in
several seems to be along the lines of "applications really ought to
consider the potential impact of caches, since caches might appear in
the request path for reasons outside the control of the application".
Classifying it as a normative reference seems like it would be
defensible (though leaving it as informative is also defensible).

NITS

Section 1

  This document contains best current practices for the specification
  of such applications.  [...]

Earlier we've talked about "applications other than Web browsing",
"protocols [that] are often ad hoc", "applications [with] multiple,
separate implementations", and "application protocol[s] using HTTP".
When we say "such applications" do we have a specific referent in mind?

Section 4.5.1

                                      Therefore, applications using
  HTTP that feel a need to allow POST queries ought consider allowing
  both methods.

All the "ought"s in -semantics made sense, but seeing as this document
is a BCP, maybe it's okay to give a more definitive recommendation?

Section 4.9.3

  One way to address this is to explicitly specify that all responses
  be fresh upon use.

I think I'm failing to parse this sentence properly, and it's unclear if
s/be/are/ is the right fix.  (In particular, what does it mean to "use"
a response?)

Section 4.16

  In HTTP, backwards-incompatible changes are possible using a number
  of mechanisms:

"A number of" implies uncertainty about exactly how many, which would
typically be accompanied by "including"; if the list is actually
exhaustive, using the actual number ("three") might be preferred.

Section 6

We refer to several other sections as being security-relevant, and the
list is almost (but not) sorted.  Should it be sorted?

[Ballot comment]
Section 2. , paragraph 5, comment:
>    *  uses an ALPN protocol ID [RFC7301] that generically identifies
>      HTTP (e.g., "http/1.1", "h2", "h2c"), or

Might want to mention "h3" as part of the examples.

-------------------------------------------------------------------------------
All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

Section 2.1. , paragraph 4, nit:
> ric/application-specific split allows a HTTP message to be handled by common
>                                      ^
Use "an" instead of "a" if the following word starts with a vowel sound, e.g.
"an article", "an hour". (Also elsewhere.)

Section 4. , paragraph 2, nit:
> mple, HTTP/2's multiplexing), this ought be noted. Applications using HTTP MU
>                                    ^^^^^^^^
Did you mean "ought to be"?

Section 4.4.1. , paragraph 6, nit:
> s can also be defined. When defining an URI scheme for an application using H
>                                      ^^
Use "a" instead of "an" if the following word doesn't start with a vowel sound,
e.g. "a sentence", "a university".

Section 4.4.2. , paragraph 2, nit:
> uests don't get sent to a "normal" Web site is likely to fail. * Features th
>                                    ^^^^^^^^
Nowadays, it's more common to write this as one word. (Also elsewhere.)

Section 4.4.3. , paragraph 2, nit:
> trieval semantics allow caching, side-effect free linking and underlies many
>                                  ^^^^^^^^^^^
Did you mean "side effect" (=adverse effect, unintended consequence)? Open
compounds are not hyphenated.

Section 4.5. , paragraph 3, nit:
> nt; doing so avoids encoding overhead and URL length limits in implementation
>                                      ^^^^
Use a comma before "and" if it connects two independent clauses (unless they
are closely connected and short).

Section 4.5. , paragraph 4, nit:
> el a need to allow POST queries ought consider allowing both methods. Applica
>                                ^^^^^^^^^^^^^^
Did you mean "ought to consider"?

Section 7.2. , paragraph 9, nit:
> Best Current Practice in the early 2000's, based on the concerns facing prot
>                                    ^^^^^^
Apostrophes aren't needed for decades.

Document references draft-ietf-httpbis-messaging-17, but -18 is the latest
available revision.

Obsolete reference to RFC5246, obsoleted by RFC8446 (this may be on purpose).

These URLs in the document can probably be converted to HTTPS:
* http://httpwg.github.io/

[Ballot comment]
Thank you to Joseph Salowey for the SECDIR review.

** Section 4.5 and 4.6. 
  ... they are
  encouraged to engage with the HTTP community early, and document
  their proposal as a separate HTTP extension, rather than as part of
  an application's specification.

Can more specificity be provided on who this “HTTP community” might be?  Is this consulting whatever is the active WG maintaining HTTP in the IETF?  The implementation community of HTTP libraries or browsers?

** Section 6.

If the transport is
  unencrypted, an attacker that can eavesdrop on HTTP communications
  can often escalate their privilege to perform operations on
  resources.

To me, eavesdrop means just the ability to read the cookie/bearer token.  An on-path attacker could also escalate privileges by modifying the cookie.  Proposing text just as:

NEW
If the transport is
  unencrypted, an attacker that can eavesdrop and/or modify HTTP communications
  can often escalate their privilege to perform operations on
  resources.


** Editorial

-- Section 3.1.
  It also allows people to leverage their
  knowledge of HTTP semantics without special-casing them

Consider using alternative wording for “special-casing”

--  Section 4.6.  Editorial.  Missing reference notation.
OLD

HTTP/2
I-D.ietf-httpbis-http2bis message format.

NEW
HTTP/2
[I-D.ietf-httpbis-http2bis] message format.

-- Section 4.6.1.  Editorial.  s/can not/cannot/

-- Section 4.9.1 and 4.9.4.  Both of these sections have illustrative examples of responses.  They are clear.  Note that Section 4.1 calls out that “[w]hen specifying examples of protocol interactions, applications should document both the request and response messages, with complete header sections, preferably in HTTP/1.1 format”.  It isn’t clear if the guidance for HTTP application (this document) should follow it’s own guidance (since this document isn’t an HTTP application).

-- Section 4.11.  Editorial.  Missing reference notation. 

OLD
HTTP/3 I-D.ietf-quic-http

NEW
HTTP/3 [I-D.ietf-quic-http]

[Ballot comment]
Hi Mark,

Thanks for this document, I found it to be a very interesting read, and I can see that this will be useful to refer to in future.

A few minor comments:

Sec 4.4.2:
"However, application-specific schemes can also be defined"

Given the previous paragraph is using 2119 language, I think that "MAY" would be better than "can also" here.

Sec 4.5.1:
Suggest changing "to have content" to "to contain content".  I had to read this a couple of times to understand that this was about the GET request sending content to the server rather than content in the response.

Sec 4.13:
Nit:
Suggest changing "consider the application actually" => "actually consider the application"

Sec: 6.1.  Privacy Considerations
"to run mobile code"
I think that it would be helpful to expand on what you mean by "to run mobile code".  I.e., I presume this is about allowing a client to send code that is executed on the server, rather than the concern being about applications that run on mobile/cell devices. ;-)

Regards,
Rob

[Ballot comment]
[S4.3, comment]

* Are all the uses of "should" here deliberately lowercase?  I got
  the feeling some of them could well have been SHOULD, e.g.,
  "Applications using HTTP SHOULD specify that ... when HTTPS is used."

[S4.5.1, nit]

* s/ought consider/ought to consider/, I suspect

[S4.5.2, question]

* Is it correct to say "OPTIONS is not the default GET method"?
  Should that be something like "not the default HTTP method"?

[S4.10, question]

* Might "ambient authority" benefit from a reference to RFC 6454
  section 8.3?

[S4.13, nit]

* "can execute script" -> "a script" or "scripts"?

[Ballot comment]
Thanks for this update. One tiny comment, to which I don't need a response:

The discussion about links in Sec 3.2 could use a reference to RFC 8288.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has reviewed draft-ietf-httpbis-bcp56bis-12, which is currently in Last Call, and has the following comments:

We understand that this document doesn't require any registry actions.

While it's often helpful for a document's IANA Considerations section to remain in place upon publication even if there are no actions, if the authors strongly prefer to remove it, we do not object.

If this assessment is not accurate, please respond as soon as possible.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2021-07-23):

From: The IESG
To: IETF-Announce
CC: Tommy Pauly , draft-ietf-httpbis-bcp56bis@ietf.org, francesca.palombini@ericsson.com, httpbis-chairs@ietf.org, ietf-http-wg@w3.org, tpauly@apple.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Building Protocols with HTTP) to Best Current Practice


The IESG has received a request from the HTTP WG (httpbis) to consider the
following document: - 'Building Protocols with HTTP'
  as Best Current Practice

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2021-07-23. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  Applications often use HTTP as a substrate to create HTTP-based APIs.
  This document specifies best practices for writing specifications
  that use HTTP to define new application protocols.  It is written
  primarily to guide IETF efforts to define application protocols using
  HTTP for deployment on the Internet, but might be applicable in other
  situations.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-httpbis-bcp56bis/



No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    rfc6454: The Web Origin Concept (Proposed Standard - Internet Engineering Task Force (IETF))
    rfc7301: Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension (Proposed Standard - Internet Engineering Task Force (IETF))
    rfc8288: Web Linking (Proposed Standard - Internet Engineering Task Force (IETF))
    rfc8615: Well-Known Uniform Resource Identifiers (URIs) (Proposed Standard - Internet Engineering Task Force (IETF))
    draft-ietf-httpbis-semantics: HTTP Semantics (None - Internet Engineering Task Force (IETF))

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up. Changes are expected over time.

This version is dated 1 November 2019.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP, which is indicated in the document header.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

This document updates advice to applications on how to use HTTP as a substrate for defining APIs. The previous guidance was from 2002, so this document does a lot to incorporate our learnings over the past 20 years.

Working Group Summary:

This document has been in the working group for quite a while now, as it was held for submission alongside the new HTTP core document revision. In general, there is good consensus. The one discussion point that arose in the WGLC which had a bit rougher consensus was about the level of normative requirement required for two issues: specifically, if use of HTTPS (HTTP with TLS) is RECOMMENDED or a MUST; and whether the use of HTTPS is a MUST for all authentication types. Some WG members do not want to make this more strict, since not all use cases for HTTP need or can use TLS; others believe that the use case addressed by this document (HTTP APIs over the Internet) is specific enough that the security requirement is appropriate.

Document Quality:

The document is well-written and carefully reviewed.

Personnel:

Shepherd: Tommy Pauly
Responsible AD: Francesca Palombini

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

I've review the document and find it ready for publication.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No concerns.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

The issue described above, regarding requirement of HTTPS, may be useful to have input from the security area on.

(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The one area I'd like to see discussed is the point about requiring HTTPS.

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

No IPR disclosures.

(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No IPR disclosures.

(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

The WG consensus seems strong, with many reviewers over a long period of time. The only disagreement outstanding is the point that has been raised earlier.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No appeals.

(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Only one nit:

  -- The draft header indicates that this document obsoletes RFC3205, but the
    abstract doesn't seem to mention this, which it should.

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

No formal review applicable.

(13) Have all references within this document been identified as either normative or informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

No.

(15) Are there downward normative references references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

Yes, it will obsolete RFC3205. This may be good to note in the abstract, which it does not currently. However, this RFC is quite old, so I'll leave it up to AD advice.

(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

No IANA Considerations.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No IANA Considerations.

(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

Not applicable.

(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

Not applicable.

As required by RFC 4858, this is the current template for the Document
Shepherd Write-Up. Changes are expected over time.

This version is dated 1 November 2019.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

BCP, which is indicated in the document header.

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

This document updates advice to applications on how to use HTTP as a substrate for defining APIs. The previous guidance was from 2002, so this document does a lot to incorporate our learnings over the past 20 years.

Working Group Summary:

This document has been in the working group for quite a while now, as it was held for submission alongside the new HTTP core document revision. In general, there is good consensus. The one discussion point that arose in the WGLC which had a bit rougher consensus was about the level of normative requirement required for two issues: specifically, if use of HTTPS (HTTP with TLS) is RECOMMENDED or a MUST; and whether the use of HTTPS is a MUST for all authentication types. Some WG members do not want to make this more strict, since not all use cases for HTTP need or can use TLS; others believe that the use case addressed by this document (HTTP APIs over the Internet) is specific enough that the security requirement is appropriate.

Document Quality:

The document is well-written and carefully reviewed.

Personnel:

Shepherd: Tommy Pauly
Responsible AD: Francesca Palombini

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

I've review the document and find it ready for publication.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No concerns.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

The issue described above, regarding requirement of HTTPS, may be useful to have input from the security area on.

(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The one area I'd like to see discussed is the point about requiring HTTPS.

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

No IPR disclosures.

(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No IPR disclosures.

(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

The WG consensus seems strong, with many reviewers over a long period of time. The only disagreement outstanding is the point that has been raised earlier.

(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No appeals.

(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Only one nit:

  -- The draft header indicates that this document obsoletes RFC3205, but the
    abstract doesn't seem to mention this, which it should.

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

No formal review applicable.

(13) Have all references within this document been identified as either normative or informative?

Yes.

(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

No.

(15) Are there downward normative references references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

Yes, it will obsolete RFC3205. This may be good to note in the abstract, which it does not currently. However, this RFC is quite old, so I'll leave it up to AD advice.

(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

No IANA Considerations.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No IANA Considerations.

(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

Not applicable.

(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

Not applicable.