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

Brian Rosen <> Tue, 14 July 2020 19:59 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 8EC963A07D4 for <>; Tue, 14 Jul 2020 12:59:15 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -1.887
X-Spam-Status: No, score=-1.887 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, HTML_MESSAGE=0.001, SPF_HELO_NONE=0.001, T_SPF_PERMERROR=0.01, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: (amavisd-new); dkim=pass (2048-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id 7e_KIY99hKpQ for <>; Tue, 14 Jul 2020 12:59:12 -0700 (PDT)
Received: from ( [IPv6:2607:f8b0:4864:20::d2d]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id 5F2883A0A8B for <>; Tue, 14 Jul 2020 12:59:12 -0700 (PDT)
Received: by with SMTP id y2so18647150ioy.3 for <>; Tue, 14 Jul 2020 12:59:12 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20150623; h=from:message-id:mime-version:subject:date:in-reply-to:cc:to :references; bh=ewdPoAQLa51MWmvH1CRZffCkQxQQzP384b3nRyO7UKw=; b=MHG0MmRFhb8sMWWnkGHX/0YFyFTbREFjAHt7Ek7q91dSkL5pMFcC2Y3zq7QNT/wejw mf+Rc5nnGIeZ9aH7Utr8qmSl0m8UnO89Efso7CgPK8WGVkyR7u1aTLT9c0Eso+A2q56I cBpa0JlrsqLI+mezOlpo06HFxYedj/VxmG8/Hns7qZlCiuIDD7n9WUwdn6V5nuRdaBQA x4s6nGck73TsXqcEPGqT/uB4GuNe5/DFnpAQ86FecyLACP2jcSHU4LKSJaU8ejkwYAJe 1dvmCE3j3uHUfoRbA/w8xjaBg5PrJFW5Td4eLVcDrk1x35XgZQey3BSs9hJOB7noK6tc B7MA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=x-gm-message-state:from:message-id:mime-version:subject:date :in-reply-to:cc:to:references; bh=ewdPoAQLa51MWmvH1CRZffCkQxQQzP384b3nRyO7UKw=; b=cANh29lBfEZiQPE74SPbwphRSwEQkjn4zHAdv5tKWVpJFgSF0URSRUjeJzXV34HkWc EEeIvkHd9PBN0KKHn7haaP1xNAK8gC1+yOhraEQOOeoKMF4ChpnCLwlUWlJNHMLjqDXX bt5FRE0rl27Qg0IZypu9hh7NjhTcg1ACjQ0NrYA3eouP9JBsAoBD3cRAMHDUYLRUWMC3 IdrWp+IYkLcoYY0qA2epP6Fx+ivdvouYZuJ3ut8URs6JH2CqwG4Xnch3/xZFeP8kWQln FBbPUoVT3/xgt3jNOuZmJ+vTpTUp69WOb9um49Nc/bNY9daUAp5MY8//cFjAjmhwRUE5 W11g==
X-Gm-Message-State: AOAM530kUsodTW7uVH2eGQX3Pe3XVDdGwuCuraLwnQTgUZlkx/HsrArr 7BVOoKjUjiFKkVCFj2iHSE6teA==
X-Google-Smtp-Source: ABdhPJzgOEsEQTgMp24adh808ns7Cv3I13Bjp8x54FI3iCWm0xq9nuEmOd6REDTGo8gD7LvxaHXeWQ==
X-Received: by 2002:a05:6638:2482:: with SMTP id x2mr7605261jat.55.1594756751581; Tue, 14 Jul 2020 12:59:11 -0700 (PDT)
Received: from brians-mbp-2871.lan ( []) by with ESMTPSA id t6sm14448ioi.20.2020. (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Tue, 14 Jul 2020 12:59:11 -0700 (PDT)
From: Brian Rosen <>
Message-Id: <>
Content-Type: multipart/alternative; boundary="Apple-Mail=_C8B9BE24-EC0D-4001-A9C3-E2FE93916FD1"
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.\))
Date: Tue, 14 Jul 2020 15:59:09 -0400
In-Reply-To: <>
Cc: Mark Nottingham <>, DISPATCH WG <>
To: Mary Barnes <>
References: <> <>
X-Mailer: Apple Mail (2.3608.
Archived-At: <>
Subject: Re: [dispatch] A WG for HTTP API Building Blocks
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DISPATCH Working Group Mail List <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Tue, 14 Jul 2020 19:59:16 -0000

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.


> On Jul 14, 2020, at 1:41 PM, Mary Barnes <> 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 < <>> 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
>  - 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 <>
> _______________________________________________
> dispatch mailing list
> <>
> <>
> _______________________________________________
> dispatch mailing list