Subject: [httpapi] Introduction

From: Christoph Kappestein <[email-masked]>
Date: Sat, 9 Jan 2021 13:10:42 +0100

Hello,

my name is Christoph I am a developer in the API space and I just
found out about
this Working-Group through this video
https://www.youtube.com/watch?v=vyeEqJNKq6Y

I am happy to see some process in this space. Currently we are working on a
JSON format called TypeSchema (https://typeschema.org/) which describes JSON
payloads and is optimized for code generation.

We have started this since there is currently no great standard which describes
JSON payloads and is optimized for code generation. So if this a topic which you
want address I would be happy to share my experiences.

In general we are also working on an open source API management product called
Fusio s. https://github.com/apioo/fusio so we are also interested in other
standards like i.e. the Deprecation header which we plan to implement, currently
we simply issue a standard "Warning" header to inform developers that an API
is deprecated, but it is great to see that there is now a dedicated header for
this.

I am not too familiar with the process to comment an RFC but is there in general
a form where I can provide written feedback to existing specifications or is
this done through this mailing list?

best regards
Christoph

---

From: Julian Reschke <[email-masked]>
Date: Sat, 9 Jan 2021 17:40:55 +0100

> https://www.youtube.com/watch?v=vyeEqJNKq6Y

Hi Christoph!

> this done through this mailing list?

RFCs, are despite their names, "finished" documents. If you find an
outright bug, you can raise an erratum
(<https://www.rfc-editor.org/errata.php>).

That said, *all* of the base HTTP specs are currently being revised
(that is HTTP/1.1 & related documents, HTTP/2), so if you have feedback
on some of these internet drafts, now is a good time to send it. For
these however, it's a different WG (HTTPBIS). You can see the documents
currently being worked on at <https://httpwg.org/> and
<https://datatracker.ietf.org/wg/httpbis/documents/>. Send feedback to
the HTTPBIS mailing list
(<https://lists.w3.org/Archives/Public/ietf-http-wg/>, or alternatively
use the issue tracker - repos at <https://github.com/httpwg>).

Similarly, for *this* WG, you can see the active documents at
<https://datatracker.ietf.org/wg/httpapi/documents/>, and send feedback
through this mailing list, or through the Github repos
(<https://github.com/ietf-wg-httpapi>).

Best regards, Julian

---

From: "Salz, Rich" <[email-masked]>
Date: Sat, 9 Jan 2021 17:40:22 +0000

The IETF has had a couple of working groups on JSON; you can find the "concluded" ones at https://datatracker.ietf.org/group/concluded/ and the active ones at https://datatracker.ietf.org/wg/  Look for "json" in the name.  Even concluded groups still have their mailing list kept open. I don't know if that will be helpful or not.  As for whether or not this WG wants to discuss this, it's up to the WG to decide if they're interested (by having this kind of discussion on the mailing list), and if necessary to work with the Area Director to determine if we need to modify the WG charter or not.

RFC's are published documents, not drafts; the name "request for comments" is a node to IETF history.  How to provide feedback on published RFC's depends on the amount and nature of feedback.  If you have a well-contained technical error, you want to report an "errata" against the RFC.  If it's more philosophical or just "more", it might be better to find the WG that published the RFC and post to that mailing list (see above).  To find the WG for rfc 1234, go to https://www.rfc-editor.org/info/rfc1234 and look at the "Source" label, which will have a link to the WG.

Hope this helps.  Welcome!

---

From: Erik Wilde <[email-masked]>
Date: Sat, 9 Jan 2021 09:49:27 -0800

hello christoph!

welcome to the group! i have nothing to add to the general remarks of 
julian, who is extremely well-versed in all things IETF.

> payloads and is optimized for code generation.

just as a pointer: https://tools.ietf.org/html/rfc8927 may be 
interesting for you, but i don't know how much overlap there is between 
TypeSchema's goals and JTD.

> want address I would be happy to share my experiences.

JTD is out there as an RFC, but that of course doesn't mean that it's 
the only way to address this use case. JTD was submitted as an 
individual draft (i.e., not via this group, which didn't yet exist when 
JTD was getting finalized), but i do think that discussing this topic 
might be interesting for this group. but that's just my personal opinion.

> is deprecated, but it is great to see that there is now a dedicated header for

that's good to see. if you end up implementing deprecation header 
support, can you please let us know so that we can add your product to 
our list of implementations? thanks!

because of https://datatracker.ietf.org/doc/draft-cedik-http-warning/ i 
am also wondering whether you use warnings for other things as well, and 
if you do, i'd be interested to hear more about it.

thanks and cheers,

dret.

-- 
erik wilde | mailto:[email-masked] |
            | http://dret.net/netdret    |
            | http://twitter.com/dret    |

---

From: Christoph Kappestein <[email-masked]>
Date: Sat, 9 Jan 2021 20:49:15 +0100

Hi all, thanks for the information and pointers.

@Julian just to get a better understanding, if we say that RFCs are finished
documents, does this mean that also those draft RFCs i.e. listed here
https://datatracker.ietf.org/wg/httpapi/documents/ are finished? I totally
understand that RFCs like 3986 are finished and will not change easily or only
in case there is an actual error. But I assumed that we can evolve and iterate
those "draft" RFCs easier until they become a "real" RFC. But this is only my
understanding from an outsider perspective so please let me know whether this
makes sense.

@Rich @Erik thanks for the pointer to JTD, this project looks indeed
interesting.
I had also some contact with the author before and I think both projects have
similar goals but there is also a feature gap. Since JTD is already an RFC it is
probably difficult to change, but if there is a way to evolve this spec I
would be really interested in this. This could then become also an interesting
alternative schema specification for the OpenAPI spec.

@Erik regarding the "Deprecation" header, sure I will let you know if we have
implemented this. I was not aware of the "Content-Warning" RFC, we use the old
"Warning" header with an 199 code only to return the status of an endpoint, we
have currently the status: Experimental, Production, Deprecated,
Closed. The status closed maps probably to the "Sunset" date at the
deprecation header RFC, in this case our gateway simply returns always an 410
status code with an info message. So we use the warning header only for this
information but I will also take a look at the Content-Warning RFC.

best regards
Christoph

---

From: "Salz, Rich" <[email-masked]>
Date: Sat, 9 Jan 2021 22:01:36 +0000

https://datatracker.ietf.org/wg/httpapi/documents  are finished? I totally

You are correct.  But the draft documents are called internet-drafts or I-D's; we don't use the term "draft RFC" because it leads to confusion.

The place to comment on those specific documents is by posting to the list.  Or raising issues on GitHub; https://github.com/ietf-wg-httpapi has repo's for each draft.

---

From: Erik Wilde <[email-masked]>
Date: Sat, 9 Jan 2021 18:04:33 -0800

hello christoph.

On 2021-01-09 11:49, Christoph Kappestein wrote:
> would be really interested in this.

the RFC is what it is. currently it's an individual submission (i.e., it 
wasn't discussed/developed in an IETF working group) and classified as 
experimental. but if there is building up momentum, it's not out of the 
question to consider updating it.

> This could then become also an interesting

absolutely. the 3.x versions of OpenAPI will keep JSON schema as a 
hard-coded part of the language, but there are plans to decouple things 
a bit more in 4.x and support alternative schema languages.

i am a fan of the idea of making OpenAPI's schema part simpler, or at 
least allowing flexibility, but the main initiative in this case will 
have to be on the OpenAPI side (which is a different group and not part 
of the IETF).

> information but I will also take a look at the Content-Warning RFC.

just as a heads up: the warning header will not be part of the revised 
HTTP version, which is one of the reasons why for the draft we have 
decided to mint a new HTTP header field.

i like the idea of signalling the "maturity stage" of an API, but it's 
hard to come up with a maturity model that fits everybody's needs. this 
is why there currently are specific headers for the API being shut down 
(the sunset RFC) and the API being deprecated (the current draft).

cheers,

dret.