[dispatch] A WG for HTTP API Building Blocks

[Mark Nottingham <[e-mail]>]

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/