Subject: [dispatch] Building Blocks for HTTP APIs - next steps

From: Mark Nottingham <[email-masked]>
Date: Fri, 31 Jul 2020 22:03:08 +1000

Hi everyone,

After some tweaks resulting from the meeting discussion, I think this charter proposal is ready to go to the ADs. Any last comments?

Cheers,

<https://gist.github.com/mnot/8a29455df65df33d92902a1ecc3e7e68>

"""
Building Blocks for 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 or applications, and it will not define new HTTP extension points, or new extensions that are likely to be used by Web browsers. APIs for HTTP itself (e.g., in clients and servers) are also out of scope.

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.
"""

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

---

From: Lucas Pardue <[email-masked]>
Date: Fri, 31 Jul 2020 13:35:16 +0100

Hey Mark,

Thanks for the updates. Where you say "or new extensions that are likely to
be used by Web browsers" is this intended to mean "solely used by Web
browsers"? Otherwise the interpretation might mean that the output be
prevented to prevent usage in Web Browsers, which seems hard to realize.

Cheers
Lucas

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 31 Jul 2020 22:41:44 +1000

Would 'implemented by' help? The intent is that if you want the browser community to pick something up, it probably needs to be in HTTP WG, but if you just want to use Fetch etc. to do it in the browser, it's not necessary to go there.

> On 31 Jul 2020, at 10:35 pm, Lucas Pardue <[email-masked]> wrote:
> 
> Hey Mark,
> 
> Thanks for the updates. Where you say "or new extensions that are likely to be used by Web browsers" is this intended to mean "solely used by Web browsers"? Otherwise the interpretation might mean that the output be prevented to prevent usage in Web Browsers, which seems hard to realize.
> 
> Cheers
> Lucas

---

From: Julian Reschke <[email-masked]>
Date: Fri, 31 Jul 2020 14:48:14 +0200

Am 31.07.2020 um 14:41 schrieb Mark Nottingham:
> ...

It helps, but the whole distinction looks weird to me.

Assume we defined a protocol for resumable uploads. Would it go here, in
HTTPBIS, or somewhere else?

Best regards, Julian

---

From: Lucas Pardue <[email-masked]>
Date: Fri, 31 Jul 2020 13:49:14 +0100

Yes I like that distinction, it makes it clear that the group's work would
not have a dependency on Browsers providing explicit interfaces or indirect
access to these APIs. Similarly, it constrains the groups work to things
that are not forbidden by Fetch [1] [2], providing some boundaries when
trying to dispatch work to HTTP or HTTPAPI WGs.

Cheers
Lucas

[1] https://fetch.spec.whatwg.org/#forbidden-method
[2] https://fetch.spec.whatwg.org/#forbidden-header-name

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 31 Jul 2020 22:50:44 +1000

I think that would be discussed between the WGs and ADs. 

Remember, we don't need an algorithm for deciding where any possible work item can go; we already have such discussions pretty often.

Cheers,

> On 31 Jul 2020, at 10:48 pm, Julian Reschke <[email-masked]> wrote:
> 
> _______________________________________________
> dispatch mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/dispatch

---

From: Julian Reschke <[email-masked]>
Date: Fri, 31 Jul 2020 14:51:14 +0200

> Building Blocks for HTTP APIs Working Group (HTTPAPI)

I understand that it says "HTTP API" because we don't want to say "REST
API" (and I agree with that).

That said, I think many people understand "HTTP API" to be an API for -
well - HTTP, such as HTTPUrlConnection, Servlets, or XMLHTTPRequest -
and these are explicitly *not* in scope here.

Maybe "HTTP based APIs" or "HTTP based Services" works better.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 31 Jul 2020 14:54:36 +0200

Am 31.07.2020 um 14:49 schrieb Lucas Pardue:
> Yes I like that distinction, it makes it clear that the group's work
> would not have a dependency on Browsers providing explicit interfaces or
> indirect access to these APIs. Similarly, it constrains the groups work

I would find that kind of dependency rather surprising in IETF work.

Are you saying that work items for HTTPBIS *do* have that dependency?

> to things that are not forbidden by Fetch [1] [2], providing some

How so?

> boundaries when trying to dispatch work to HTTP or HTTPAPI WGs.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 31 Jul 2020 23:02:03 +1000

> Maybe "HTTP based APIs" or "HTTP based Services" works better.

In my experience, the people who this WG are targeting will understand "HTTP APIs." 

Note that "Building Blocks for..." has been added to the full WG name, which should help address this.

---

From: Lucas Pardue <[email-masked]>
Date: Fri, 31 Jul 2020 14:48:58 +0100

> Are you saying that work items for HTTPBIS *do* have that dependency?

Forgive my overreaching language. I was speaking to the notion of running
code or intent to implement, for instance, examples I have seen are things
like cache digest. A more recent example would be WebTransport that is
splitting the work between protocol and API between IETF and W3C
respectively. I don't believe HTTPBIS has such dependencies now, but for
dispatching new work I think it is useful to know that something requiring
W3C liason is probably beyond scope for HTTPAPI.

> > to things that are not forbidden by Fetch [1] [2], providing some

I mean if someone has an idea that works in the machine-to-machine realm
and is looking to run this on the Web, their analysis may identify that
`Sec-` prefix is needed and as such it is not a candidate for HTTPAPI.

Cheers
Lucas

---

From: Wenbo Zhu <[email-masked]>
Date: Fri, 31 Jul 2020 10:46:38 -0700

On Fri, Jul 31, 2020 at 5:51 AM Julian Reschke <[email-masked]>
wrote:

> > After some tweaks resulting from the meeting discussion, I think this
> charter proposal is ready to go to the ADs. Any last comments?
> >
> > Cheers,
> >

While I agree with Julian's concern here, ironically I named the doc that
specifies how http is used for the public cloud-apis I work on exactly as
"http-apis" ...

The text is not very clear on the exact scope though:

> HTTP is often for not only Web browsing, but also machine-to-machine
communication ....

Are we talking about "HTTP as a transport" here, which includes e.g. "apis"
(external consumption, e.g. ws), micro-services (rpcs), messaging
frameworks, non-browser-clients etc etc ... ?

> broad representation from across the industry -- e.g., API gateway
vendors (and other intermediaries), API consultants, API tool vendors,
in-house API team

This seems to suggest we are only interested in use cases when HTTP is used
as the transport for public API end-points

---

From: Rob Sayre <[email-masked]>
Date: Fri, 31 Jul 2020 17:18:51 -0700

> charter proposal is ready to go to the ADs. Any last comments?

It might be good to address the value this effort will add in addition to
things like GraphQL:

https://thenewstack.io/graphql-gets-its-own-foundation/

thanks,
Rob