Supported RFCs registry

[derekm]

Can JAX-RS make and keep a registry of all RFCs that are intended to be satisfied by its specification?

[mkarg]

Is this a question or a proposal? ;-) What do you expect from this registry? And how frequently shall it change?

My personal opinion is that JAX-RS should only use and implement RFCs which are on the STD1 track. The reason is that JAX-RS is an API, not a framework. Hence it should concentrate on the essence of what all JAX-RS implementors actually do support, which is quite the opposite of mandating additional RFCs to be supported. If only one implementor restricts non-STD RFCs, he would be non-compliant. If the rare case happens a proposed standard is withdrawn, we cannot remove it from JAX-RS before the next major (!) release, and even that would cause lots of trouble.

In case the JSR 311, JSR 339 or JSR 370 EGs, including myself, actually adoped non-STD 1 RFCs, then "mea culpa", but it was a bad decision.

The right way to deal with non-STD1 RFCs simply is to have an external incubator project ontop of JAX-RS, which provides the particular features of that RFC, and to add that one to the application. Once the RFC is adopted to STD1, it should become adopted by JAX-RS.

Again, this is my personal opinion. Other committers, contributors, project leads or PMC members might have a different opinion.

[derekm]

It is a proposal in the form of a question! :)

A list of supported RFCs is required to even see if there has ever been a "STD-1 inclusion" criteria before.

For more information on what you're talking about: https://tools.ietf.org/html/rfc1796

[mkarg]

@derekm Feel free to more concisely describe what you want the JAX-RS project to provide in the technical sense. A web site? A Java enum being part of JAX-RS API? An appendix of the spec PDF?

[derekm]

For example, to address your opinion, @PATCH should not be supported by JAX-RS 2.1, since it is not a standard:

Here it is declared experimental/unsupported/nonstandard/unreliable: https://tools.ietf.org/html/rfc2068#section-19.6.1.1

Here it is pushed aside: https://tools.ietf.org/html/rfc2616#page-175

Here it is referred to by its "PROPOSED STANDARD" RFC: https://tools.ietf.org/html/rfc7231#page-29

PROPOSAL: An early, definitive section of the spec should list all of the RFCs that are intended to be satisfied and adhered to.

[spericas]

The JAX-RS spec consists of a PDF document and some Javadocs. There are some (likely not all) RFC's referenced at both location. The Bibliography section of the spec lists a few and so do the Javadocs. I don't see the point of adding another document list these (why not another for JSRs etc?), instead we should make sure we have all the necessary references at the existing locations.

[derekm]

@spericas -- The RFCs that are declared as supported should be a normative part of the spec. They should be listed explicitly instead of incidentally, otherwise there is no way to QA the spec against the RFCs.

[derekm]

In other words, some RFCs in footnotes & bibliography might be normative and some might be non-normative. In order to QA the JAX-RS spec or confirm its correctness, we need to know all of the RFCs that are considered normative for JAX-RS.

[spericas]

@derekm Everything in the spec is normative unless marked as non-normative (see Section 1.4).

[derekm]

@spericas -- What does the spec declaring itself normative have to do with being able to audit the spec against the RFCs it claims to be compliant with?

[leewalton]

+1 for publishing a concise list of the RFCs, JSRs, or other specifications that the JAX-RS API and its implementors must be compliant with.

[spericas]

@spericas -- What does the spec declaring itself normative have to do with being able to audit the spec against the RFCs it claims to be compliant with?

Nothing, I was just answering to your comment that some things may not be normative in the spec.

[Bo98]

Apologies for being late to the party here but I saw some of the comments on #582 and had to chip in.

I think the mentality of avoid "proposed standards" at all costs is a little ridiculous considering HTTP itself has never reached internet standard status. The 2nd RFC of HTTP 1.1 (from 1999), RFC 2616, did reach one stage past "proposed" in the form of a "draft standard" - but such a step no longer exists.

Though now it's been replaced with the RFC 7230 family of RFCs, the reference to RFC 2616 has been wiped from the "Official Internet Protocol Standards" registry and replaced with RFC 7230-7235. RFC 7230-7235 are only "proposed" but there is also no longer any HTTP RFC with a higher status in the registry. RFC 2616 should be treated as obsolete, just as it has been marked as.

And before someone mentions STD 1 - it was replaced by the above registry 5 years ago.

However I do understand concerns about the difficulty of withdrawing API in the extremely rare scenario of a RFC being withdrawn (though I think the scenario of it being made obsolete by another RFC like RFC 2616 did is far more likely). If you want to make sure an RFC has a certain level of maturity before implementing it, then fair enough - document that. But I don't think "proposed standard" is the correct indicator to reject additions. For internet drafts (not to be confused with "draft standard"), yes reject them - but that goes without saying.

With the much quicker pace that the web is evolving (HTTP/3 drafts are being prepared already, likely taking this draft as a base similar to how HTTP/2 based off of SPDY), I don't think we'll see any HTTP RFC become an "internet standard" for the foreseeable future. 15 years wasn't long enough for RFC 2616.