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

Mary Barnes <mary.ietf.barnes@gmail.com> Tue, 14 July 2020 20:32 UTC

Return-Path: <mary.ietf.barnes@gmail.com>
X-Original-To: dispatch@ietfa.amsl.com
Delivered-To: dispatch@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id ED1573A0B2A for <dispatch@ietfa.amsl.com>; Tue, 14 Jul 2020 13:32:17 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.097
X-Spam-Level:
X-Spam-Status: No, score=-2.097 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, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, SPF_HELO_NONE=0.001, 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=gmail.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 8uEAqqTEvF7r for <dispatch@ietfa.amsl.com>; Tue, 14 Jul 2020 13:32:15 -0700 (PDT)
Received: from mail-pj1-x1034.google.com (mail-pj1-x1034.google.com [IPv6:2607:f8b0:4864:20::1034]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 8308C3A082B for <dispatch@ietf.org>; Tue, 14 Jul 2020 13:32:15 -0700 (PDT)
Received: by mail-pj1-x1034.google.com with SMTP id t15so2128398pjq.5 for <dispatch@ietf.org>; Tue, 14 Jul 2020 13:32:15 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=Ieb/kohMwIKL7kkQOGYUHCBhG10x/ptUreZBZY0TkLc=; b=X/cGaJYf1tAYXWnnpsmD+g2fMz1ZgeCnitBl4a6l79IT8r/oeDU6QJfRvDHdS9vz+D fWIW/LEdhvrIePNEQkJBZWl29EZnoJgytEGgLfO5bas+gAq+NBZHU0J1DSCT3Cw4hLEa xJbSMg2RZG4LhOP/6tI6C7ZuAKU41P/qfwB4ouwaNki8/QT0hVOrjQL5bJBVgipae2hT fJ/nqz8VtLkT2Afr1DMw2sS4SAGjLS2F781+ne0ymU0YI6v5ABL1rIXcFM+bzLBzA/iW JkZSZKMd7m07fqRQbxIGixuoBudd9NYFtUAt2VHylVMcJqso8ZsMkjMuSSJDLw63H0wF SPdw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=Ieb/kohMwIKL7kkQOGYUHCBhG10x/ptUreZBZY0TkLc=; b=US45WBoftmupnkDWvwNhbNWIx8AYCHT3pk8fMEngqJRUx4U5elz91IxexBuIEl3I4D XPv0pn0v2V92XzfQn5B7LFHjIb2xCHcAHylZVst6zlfbFFuSx0crq07HaKFu46tC9rSf LIaNVbsIMOoG2XrrKDgf4nQokYlDm5BLsOr7smyhnl+wacmphsE6nrdtFdeLZd3eF8Bo IryKoPoS4pNJmd0nzrOwA5AGCljMnbGd0yAO4Dxfr28b5i8noNiyfGb+tBybij3JrhPz y/wUOBPYpc5kiIacHyYSRPbLwteQ2M6gMArFApmPS3yfEm3RqOpkQWh//5AOOgw5kxg4 ZgZA==
X-Gm-Message-State: AOAM533HM8IN0NKwNhEudqPXlmRREEMmslD2DRtlx5W/djwZZJzJieS/ r9Q1ko5F8UXZuVZUkmDotWl1HKgaTZSaMOkz6xXryg==
X-Google-Smtp-Source: ABdhPJyk1bAj99TaBrlYg6xj+N35nv3JdFn6ETUUPn3B9vqm/u0xVcftzGtiGfUbTqF7fRO9pcUrq5W9Tn1OuX8ByQU=
X-Received: by 2002:a17:902:103:: with SMTP id 3mr5437447plb.195.1594758734850; Tue, 14 Jul 2020 13:32:14 -0700 (PDT)
MIME-Version: 1.0
References: <111A89F4-CBD6-4C63-A45A-C7458E7413FF@mnot.net> <CAHBDyN7BGsBJ4=+boBAAP5Z+ZT+pFfQ-iJtSa7qHNTP_bGyXeQ@mail.gmail.com> <7414026C-4726-4C8E-8C9C-60A81F5456B5@brianrosen.net>
In-Reply-To: <7414026C-4726-4C8E-8C9C-60A81F5456B5@brianrosen.net>
From: Mary Barnes <mary.ietf.barnes@gmail.com>
Date: Tue, 14 Jul 2020 15:32:03 -0500
Message-ID: <CAHBDyN6h_x_Q5x-bHXYKoPV0Rdchq8mCuz1NfNUbJ5k1tib4tg@mail.gmail.com>
To: Brian Rosen <br@brianrosen.net>
Cc: Mark Nottingham <mnot@mnot.net>, DISPATCH WG <dispatch@ietf.org>
Content-Type: multipart/alternative; boundary="000000000000e4aee705aa6cb3e2"
Archived-At: <https://mailarchive.ietf.org/arch/msg/dispatch/5NYsPamFzte736LPHVMv4HXYD5E>
Subject: Re: [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 20:32:18 -0000

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 <br@brianrosen.net> 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.
>
> 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 <mary.ietf.barnes@gmail.com>
> 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 <mnot@mnot.net> 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   https://www.mnot.net/
>>
>> _______________________________________________
>> dispatch mailing list
>> dispatch@ietf.org
>> https://www.ietf.org/mailman/listinfo/dispatch
>>
> _______________________________________________
> dispatch mailing list
> dispatch@ietf.org
> https://www.ietf.org/mailman/listinfo/dispatch
>
>
>