Subject: [dispatch] A WG for HTTP API Building Blocks

From: Mark Nottingham <[email-masked]>
Date: Tue, 14 Jul 2020 11:36:25 +1000

I've been chatting with folks in the background for a while about starting a WG to take on specs to help folks building HTTP APIs.[1]

HTTP has been used for machine-to-machine communication for most of its lifetime, there are a number of functions that are designed and implemented in an ad hoc fashion, or with several competing approaches. Establishing a WG to standardise some common functions might help, both by documenting some common building blocks, and serving as a locus for a new community -- one that's related to but distinct from the HTTP WG.

For example, these specifications were either AD-sponsored or on the Independent stream, but could have been in-scope for such a WG:
 - rfc6570 URI Template
 - rfc6892 The 'describes' Link Relation Type
 - rfc6901 JSON Pointer
 - rfc6902 JSON Patch
 - rfc7807 Problem Details for HTTP APIs
 - rfc8288 Web Linking
 - rfc8594 The Sunset HTTP Header Field
 - rfc8631 Link Relation Types for Web Services

... and there are also a number of current drafts that such a WG might consider, e.g.:
 - draft-wilde-linkset
 - draft-nottingham-link-hint
 - draft-dalal-deprecation-header
 - draft-polli-ratelimit-headers

This is the proposed charter:
~~~
HTTP APIs Working Group (HTTPAPI)

HTTP is often for not only Web browsing, but also machine-to-machine communication, often called 'HTTP APIs'. This Working Group will standardise HTTP protocol extensions for use in such cases, with a focus on building blocks for separate or combined use.

Its output can include:
	• Specifications for new HTTP header and/or trailer fields
	• Specifications for new message body formats, or conventions for use in them (e.g., patterns of JSON objects)
	• Proposals for new HTTP status codes, methods, or other generic extensions, to be considered by the HTTP Working Group
	• Best practices and other documentation for HTTP API designers, consumers, implementers, operators, etc.

Other items are out of scope. In particular, this WG will not take on work items for APIs for specific use cases, and it will not define new HTTP extension points, or new extensions that are likely to be used by Web browsers.

New work items can be added after a Call for Adoption on the working group mailing list and consultation with the Area Director.

To be successful, this Working Group will need to have active and broad representation from across the industry -- e.g., API gateway vendors (and other intermediaries), API consultants, API tool vendors, in-house API teams. Therefore, adopted proposals should have public support from multiple implementers and/or deployments before being sent to the IESG.

This Working Group will need to coordinate closely with the HTTP Working Group.
~~~

Because a large part of the task here is building a representative community, I think this group should be chartered without specific documents; it can deliberate on what's appropriate to start with once constituted. It should also be periodically evaluated to make sure that it's functioning well and representative of the greater community, with the assumption that if it isn't, it would be closed (I'd hope that ADs do that for every WG anyway, but since this is trying to establish a new venue, it should be considered on probation).

The ADs have responded positively, and asked me to bring this to DISPATCH for wider review. I'm happy to talk about it in the meeting if there's time.

Cheers,

1. a.k.a. "RESTful APIs", although that's a misunderstanding of what REST is.

--
Mark Nottingham   https://www.mnot.net/

---

From: "Bron Gondwana" <[email-masked]>
Date: Tue, 14 Jul 2020 11:49:41 +1000

> I've been chatting with folks in the background for a while about starting a WG to take on specs to help folks building HTTP APIs.[1]

I support this idea.

> - draft-polli-ratelimit-headers

Particularly with such a large set of evidence in favour of the need for it!

I do feel that there's some crossover to consider with the WPACK working group's work and non-realtime transfer of data.

Cheers,

Bron.

--
 Bron Gondwana, CEO, Fastmail Pty Ltd
 [email-masked]

---

From: Mary Barnes <[email-masked]>
Date: Tue, 14 Jul 2020 12:41:36 -0500

I think it's a great idea and yes on [1] - the vast majority don't
understand REST.    And, not all HTTPS APIs that are called RESTful (or
even worse "REST API"s) actually follow the REST model - i.e., folks are
using it as a generic term for any API using HTTPS.

Regards,
Mary.

On Mon, Jul 13, 2020 at 8:36 PM Mark Nottingham <[email-masked]> wrote:

> I've been chatting with folks in the background for a while about starting
> a WG to take on specs to help folks building HTTP APIs.[1]
>
> HTTP has been used for machine-to-machine communication for most of its
> lifetime, there are a number of functions that are designed and implemented
> in an ad hoc fashion, or with several competing approaches. Establishing a
> WG to standardise some common functions might help, both by documenting
> some common building blocks, and serving as a locus for a new community --
> one that's related to but distinct from the HTTP WG.
>
> For example, these specifications were either AD-sponsored or on the
> Independent stream, but could have been in-scope for such a WG:
>  - rfc6570 URI Template
> HTTP is often for not only Web browsing, but also machine-to-machine
> communication, often called 'HTTP APIs'. This Working Group will
> standardise HTTP protocol extensions for use in such cases, with a focus on
> building blocks for separate or combined use.
>
> Its output can include:
>         • Specifications for new message body formats, or conventions for
> use in them (e.g., patterns of JSON objects)
>         • Proposals for new HTTP status codes, methods, or other generic
> extensions, to be considered by the HTTP Working Group
> Other items are out of scope. In particular, this WG will not take on work
> items for APIs for specific use cases, and it will not define new HTTP
> extension points, or new extensions that are likely to be used by Web
> browsers.
>
> New work items can be added after a Call for Adoption on the working group
> mailing list and consultation with the Area Director.
>
> To be successful, this Working Group will need to have active and broad
> representation from across the industry -- e.g., API gateway vendors (and
> other intermediaries), API consultants, API tool vendors, in-house API
> teams. Therefore, adopted proposals should have public support from
> multiple implementers and/or deployments before being sent to the IESG.
>
> Because a large part of the task here is building a representative
> community, I think this group should be chartered without specific
> documents; it can deliberate on what's appropriate to start with once
> constituted. It should also be periodically evaluated to make sure that
> it's functioning well and representative of the greater community, with the
> assumption that if it isn't, it would be closed (I'd hope that ADs do that
> for every WG anyway, but since this is trying to establish a new venue, it
> should be considered on probation).
>
> The ADs have responded positively, and asked me to bring this to DISPATCH
> for wider review. I'm happy to talk about it in the meeting if there's time.
>
> Cheers,
>
>
> _______________________________________________
> dispatch mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/dispatch
>

---

From: Brian Rosen <[email-masked]>
Date: Tue, 14 Jul 2020 15:59:09 -0400

Don’t get me started on what is and isn’t RESTful.  There is NO definition, no generally accepted standard, and not even commonly agreed principals.  It’s a wild, Wild West and anyone that claims to know what is and isn’t RESTful is, IMHO, mistaken.  Fortunately, we don’t need to have such a definition to do all these good things.

In fact, it's good that the charter avoids saying REST.  I’d like to keep it that way.

One question about the charter:  We’re going to see an increasing incidence of defining protocols using json and HTTP in our work.  It would be good if the IETF had some common way these interfaces were defined: not just the schemas but the operations.  This is the domain of OpenAPI, for example, which could be a candidate for what I’m asking about.  Is that something that would be a chartered item?  I’d be willing to work on that.  Not proscriptive, just advisory — there are going to be plenty of interfaces that wouldn’t fit, but things that use an HTTP verb, take some parameters in, possibly including json objects, and return some json response could benefit from some common defined way to describe them.

Brian

> On Jul 14, 2020, at 1:41 PM, Mary Barnes <[email-masked]> wrote:
> 
> I think it's a great idea and yes on [1] - the vast majority don't understand REST.    And, not all HTTPS APIs that are called RESTful (or even worse "REST API"s) actually follow the REST model - i.e., folks are using it as a generic term for any API using HTTPS. 
> 
> Regards,
> Mary. 
> 
> On Mon, Jul 13, 2020 at 8:36 PM Mark Nottingham <[email-masked] <mailto:[email-masked]>> wrote:
> .... and there are also a number of current drafts that such a WG might consider, e.g.:
>  - draft-wilde-linkset
> Mark Nottingham   https://www.mnot.net/ <https://www.mnot.net/>
> 
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/dispatch <https://www.ietf.org/mailman/listinfo/dispatch>

---

From: Mary Barnes <[email-masked]>
Date: Tue, 14 Jul 2020 15:32:03 -0500

I would be very, very happy to avoid the term REST altogether as well.
 And, I'll be very happy if this work moves forward and I can point folks
to this when they try to tell me they're developing or have defined a
REST/ful API.

On Tue, Jul 14, 2020 at 2:59 PM Brian Rosen <[email-masked]> wrote:

> Don’t get me started on what is and isn’t RESTful.  There is NO
> definition, no generally accepted standard, and not even commonly agreed
> principals.  It’s a wild, Wild West and anyone that claims to know what is
> and isn’t RESTful is, IMHO, mistaken.  Fortunately, we don’t need to have
> such a definition to do all these good things.
>
> One question about the charter:  We’re going to see an increasing
> incidence of defining protocols using json and HTTP in our work.  It would
> be good if the IETF had some common way these interfaces were defined: not
> just the schemas but the operations.  This is the domain of OpenAPI, for
> example, which could be a candidate for what I’m asking about.  Is that
> something that would be a chartered item?  I’d be willing to work on that.
> Not proscriptive, just advisory — there are going to be plenty of
> interfaces that wouldn’t fit, but things that use an HTTP verb, take some
> parameters in, possibly including json objects, and return some json
> response could benefit from some common defined way to describe them.
>
> Brian
>
>> I've been chatting with folks in the background for a while about
>> starting a WG to take on specs to help folks building HTTP APIs.[1]
>>
>> Other items are out of scope. In particular, this WG will not take on
>> work items for APIs for specific use cases, and it will not define new HTTP
>> New work items can be added after a Call for Adoption on the working
>> group mailing list and consultation with the Area Director.
>>

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 15 Jul 2020 09:25:08 +1000

Hi Brian,

> On 15 Jul 2020, at 5:59 am, Brian Rosen <[email-masked]> wrote:
> 

My .02 - I think it might be eventually, but I'd like to see the WG build some capacity and legitimacy first. I say that because there are some issues (like interface description) that have multiple possible solutions, and I don't think we should be in the business of 'picking winners' unless we are able to demonstrate that we have engagement broadly across the industry. Hence the focus on 'building blocks' rather than complete solutions.

Cheers,

---

From: Lucas Pardue <[email-masked]>
Date: Wed, 15 Jul 2020 00:36:31 +0100

Hey Mark,

I think this is a good idea in general.

> extension points, or new extensions that are likely to be used by Web

On a personal note, I struggle a bit to understand how some proposal "foo"
would be demarcated as HTTP vs HTTP API. That is probably case in point for
the need of a community that understands these things better than me.
I suspect my problem is that the interpretation of browsing is a little
open and the charter could benefit from being arbitrarily more explicit.
For instance, one pattern that is emerging is building Internet
applications around the Web Platform but otherwise not supporting the
notion of "general purpose web browsing", examples I have in mind are
Progressive Web Apps, applications built on top of Electron, or "TV apps"
in media clients. Therefore, the statement "[will not define] new
extensions that are likely to be used by Web browsers" seems to rule out
technologies and that seems a bit unfair.

Cheers,
Lucas

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 15 Jul 2020 16:14:51 +1000

Hi Lucas,

> On 15 Jul 2020, at 9:36 am, Lucas Pardue <[email-masked]> wrote:
> 
> On a personal note, I struggle a bit to understand how some proposal "foo" would be demarcated as HTTP vs HTTP API. That is probably case in point for the need of a community that understands these things better than me. 

There's definitely a grey area, and I suspect it will take communication and negotiation -- which is often the case between WGs anyway (we've had several of these kinds of interactions between HTTP and other groups like QUIC, DISPATCH and SECDISPATCH).

> I suspect my problem is that the interpretation of browsing is a little open and the charter could benefit from being arbitrarily more explicit. For instance, one pattern that is emerging is building Internet applications around the Web Platform but otherwise not supporting the notion of "general purpose web browsing", examples I have in mind are Progressive Web Apps, applications built on top of Electron, or "TV apps" in media clients. Therefore, the statement "[will not define] new extensions that are likely to be used by Web browsers" seems to rule out technologies and that seems a bit unfair.

One differentiating factor is whether the new protocol element is likely to be supported in the Web Platform itself (i.e., actually by the browser), or by code that's running in the browser on behalf of the origin. Would that help, if stated as general guidance (I don't think it should be an inflexible rule)?

Cheers,

---

From: Anders Rundgren <[email-masked]>
Date: Wed, 15 Jul 2020 09:40:34 +0200

A long time source of frustration has been and still is the case of "Signed HTTP Requests".
The limited progress in this space have forced other parties to step in, more recently including ETSI with Open Banking as initial target.
FWIW, I'm personally working on such a scheme that facilitate serialization which in turn enables counter-signing.  It is based on RFC 8785.

thanx,
Anders

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 15 Jul 2020 23:32:45 +1000

FYI:
  https://tools.ietf.org/html/draft-ietf-httpbis-message-signatures-00

Cheers,

> On 15 Jul 2020, at 5:40 pm, Anders Rundgren <[email-masked]> wrote:
>

---

From: Anders Rundgren <[email-masked]>
Date: Wed, 15 Jul 2020 15:47:15 +0200

>    https://tools.ietf.org/html/draft-ietf-httpbis-message-signatures-00

Better late than never :)

Anders

---

From: Michael Toomim <[email-masked]>
Date: Thu, 16 Jul 2020 00:56:09 -0700

I also see value in recruiting API developers and consumers, but (like Lucas) I struggle to distinguish whether a particular proposal "foo" would be demarcated as HTTP vs. HTTP API.

As a present example, how do we classify the Braid proposal?

    https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http

On the one hand, we could describe it as "push-update for REST APIs", and then put it into the HTTP API bucket.

But on the other, Braid also applies to browsers and proxies, where it improves caching, reduces network traffic, and allows pages to update automatically without a reload button.  That sounds like core HTTP.

Historical examples could also be interesting.  How do we classify HTTP Live Streaming?

    https://tools.ietf.org/html/rfc8216

This is an API standard, which does not need special browser support.  However, most mobile browsers (but not desktop) now have native implementations for better performance.  Does that make it HTTP core?

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 16 Jul 2020 18:09:38 +1000

Great example. 

I think that if you got HTTP WG folks excited about BRAID and some folks putting their hands up to implement it there, it would take it on. So far, the reaction has been of interest, but I'm not sure we're quite to the point where we'll adopt it; personally I'm still looking for more people to say 'yes, I want to implement that' and/or 'yes, I have a use case for that.' That may still happen, in time.

If not, and we had an HTTP APIs WG, you could take it there and see if you could get traction with that community; since it's not defining new methods or status codes, and it doesn't necessarily need browser implementation to be useful, that should work.

There's one proviso, however; if the HTTP WG thought it was a bad idea (e.g., actively harmful, bad for HTTP, conflicting with other work, or just a bad starting point for work) it wouldn't be good for the HTTP APIs WG to take it on, because that would be 'venue shopping.'

Does that help? 

> On 16 Jul 2020, at 5:56 pm, Michael Toomim <[email-masked]> wrote:
>

---

From: Michael Toomim <[email-masked]>
Date: Thu, 16 Jul 2020 02:00:04 -0700

Thanks Mark, but my question wasn't about how to get a particular proposal adopted.  I'm trying to find clarity on how we would distinguish these two working groups.

The purpose of these two examples (one current proposal, one historical) is just to give us something concrete to deliberate.  Are these examples of HTTP work, or HTTP API work?

Distinguishing these groups seems important because they are so similar.  If we have trouble identifying which group should take which work right now, when nothing is at stake, I could imagine difficulties at scale.  I'd love to find some clear criteria.

> On Jul 16, 2020, at 1:09 AM, Mark Nottingham <[email-masked]> wrote:
> 
> Great example. 
>

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 16 Jul 2020 19:12:07 +1000

It's not necessary to have a mechanical process for determining what group something best belongs in; it's negotiated between the various stakeholders, following any guidance in the RFCs and charters as appropriate. As I mentioned to Lucas, we already encounter this sort of situation in other places (e.g., deciding whether a particular HTTP/3 extension belongs in the QUIC WG, the HTTP WG, or another WG dedicated to that extension's use case).

Cheers,

> On 16 Jul 2020, at 7:00 pm, Michael Toomim <[email-masked]> wrote:
>