[dispatch] A WG for HTTP API Building Blocks

Mark Nottingham <mnot@mnot.net> Tue, 14 July 2020 01:36 UTC

Return-Path: <mnot@mnot.net>
X-Original-To: dispatch@ietfa.amsl.com
Delivered-To: dispatch@ietfa.amsl.com
Received: from localhost (localhost []) by ietfa.amsl.com (Postfix) with ESMTP id 9498C3A07E3 for <dispatch@ietfa.amsl.com>; Mon, 13 Jul 2020 18:36:32 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.12
X-Spam-Status: No, score=-2.12 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=mnot.net header.b=TS3o1sw7; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=t3pqeFji
Received: from mail.ietf.org ([]) by localhost (ietfa.amsl.com []) (amavisd-new, port 10024) with ESMTP id f0QXJf3_UQpv for <dispatch@ietfa.amsl.com>; Mon, 13 Jul 2020 18:36:31 -0700 (PDT)
Received: from wout1-smtp.messagingengine.com (wout1-smtp.messagingengine.com []) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id E709F3A077A for <dispatch@ietf.org>; Mon, 13 Jul 2020 18:36:30 -0700 (PDT)
Received: from compute4.internal (compute4.nyi.internal []) by mailout.west.internal (Postfix) with ESMTP id 0F1AE268 for <dispatch@ietf.org>; Mon, 13 Jul 2020 21:36:29 -0400 (EDT)
Received: from mailfrontend1 ([]) by compute4.internal (MEProxy); Mon, 13 Jul 2020 21:36:30 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mnot.net; h=from :content-type:content-transfer-encoding:mime-version:subject :message-id:date:to; s=fm3; bh=XV8jCMqnz8rdXPdUFI2v+vd4WlW9bndE5 UFtCdG7Kx0=; b=TS3o1sw7YK5iymrXDrC4XkrSQdBH+LEFm+hg+KZwPPPINEO0a HHFi3H8LjSuF3BM2Cg7+VK9GTvLRN2abMMZtA1uPnqBZnCNX9nlMKtG64GbGUzL7 mGFGxqJxtXJyBsNQ0bYCfqxCooCTDTk2nVFvDDE+hcGPl4OALdTrOdq+8e6KCfz8 TCj2FmPVGPRxNRwxkq2HneUZ4b3MHJVJjB80dI8tdNeqxnL3tmSxQFAW81aKNTKE W/6pgii3aV95B7Cn/eVqVQEpg2Z5kn8DHTX7MugSO4/dVa1/QL0o8uNbFWLv8fvW LD38cLUFbzofxbOdUnNkqroituQ2zrosAqauQ==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-transfer-encoding:content-type :date:from:message-id:mime-version:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; bh=XV8jCM qnz8rdXPdUFI2v+vd4WlW9bndE5UFtCdG7Kx0=; b=t3pqeFjihiFMwZkjNdezBb z4Gca46WmIVEMgrlp58zaNr/u8dhfCJcv3AiUdq9Dv0JFX6yBud6F+czemii78BD NA6R9XHPl/ecIaj/kQ5uSkekNfWpe8IUFKlZkVnzIC7D/SEocO+ZMHNICl2HdfKk CgwppIPnWNGnQwZDdyTqIi4FP2BRe8u7TuhPJFOb0LQkztQTtcRI49h5sX7iCrSV ODyZ5kMxaXwvfuIbpv+U75/xX9KZuBBTyv/sXKgAN1VHY1dvtKoxdz439zvktikt eByk4/2bGzQA9AVw1LwDArs3yHe1VvmUGAEmLVFD11960ZMyoi/Cuw4TTO62GYnA ==
X-ME-Sender: <xms:HAwNX835hy8QBXPbdumLTvO-uC9wWwDBYuOnHJZTVM-3ZDHoPx-Sgg>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrvdelgdegiecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefhtgfgggfukfffvffosehtqhhmtdhhtdejnecuhfhrohhmpeforghrkhcupfho thhtihhnghhhrghmuceomhhnohhtsehmnhhothdrnhgvtheqnecuggftrfgrthhtvghrnh eptdevteeujedufedtgeeggfehlefhtdeludetieekvedtledutdfhffekkeetvedtnecu ffhomhgrihhnpehmnhhothdrnhgvthenucfkphepudduledrudejrdduheekrddvhedune cuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepmhhnohht sehmnhhothdrnhgvth
X-ME-Proxy: <xmx:HAwNX3GmRb7BYdLe14WVl425-QqE359v7YC_7B8O15TBdaG_60VrJQ> <xmx:HAwNX068vfxFjcZ_-s-9UdmXZLEkkebwt2M-plGUT_tBwlibAFFQlQ> <xmx:HAwNX12twpTbI_yRmiCGPENMuCZuzYVGwldbe9dMuBfb7jw8U_Rhjg> <xmx:HQwNXyPV_D0rnvHCMVptWnAPJHRaPOdMzQkO3b8zwcK3F-_uv4_CLQ>
Received: from marks-air.mnot.net (119-17-158-251.77119e.mel.static.aussiebb.net []) by mail.messagingengine.com (Postfix) with ESMTPA id 50CEB3280063 for <dispatch@ietf.org>; Mon, 13 Jul 2020 21:36:28 -0400 (EDT)
From: Mark Nottingham <mnot@mnot.net>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.\))
Message-Id: <111A89F4-CBD6-4C63-A45A-C7458E7413FF@mnot.net>
Date: Tue, 14 Jul 2020 11:36:25 +1000
To: DISPATCH WG <dispatch@ietf.org>
X-Mailer: Apple Mail (2.3608.
Archived-At: <https://mailarchive.ietf.org/arch/msg/dispatch/pWx1SgjZS4R3nzXEK-jE6xqOqUc>
Subject: [dispatch] A WG for HTTP API Building Blocks
X-BeenThere: dispatch@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DISPATCH Working Group Mail List <dispatch.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/dispatch>, <mailto:dispatch-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/dispatch/>
List-Post: <mailto:dispatch@ietf.org>
List-Help: <mailto:dispatch-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/dispatch>, <mailto:dispatch-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 14 Jul 2020 01:36:33 -0000

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.


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

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