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

Darrel Miller <Darrel.Miller@microsoft.com> Thu, 30 July 2020 03:05 UTC

Return-Path: <Darrel.Miller@microsoft.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 413923A0C06 for <dispatch@ietfa.amsl.com>; Wed, 29 Jul 2020 20:05:53 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2
X-Spam-Level:
X-Spam-Status: No, score=-2 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, HTTPS_HTTP_MISMATCH=0.1, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=microsoft.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 YcDKDbz62cO9 for <dispatch@ietfa.amsl.com>; Wed, 29 Jul 2020 20:05:49 -0700 (PDT)
Received: from NAM06-DM3-obe.outbound.protection.outlook.com (mail-eopbgr640104.outbound.protection.outlook.com [40.107.64.104]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 24AE73A0C02 for <dispatch@ietf.org>; Wed, 29 Jul 2020 20:05:48 -0700 (PDT)
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=YAGDJ3gUwAKEtJ5iL66suu27TJwnImev1UMXpWWSDToxjSfc4lEPs3w8IF/pBjeZwG0UbxrslyLdgCCUAKtm/8cce3KBbd+Kk0L4bf1jcn97721wgYXwhugNIWm4sE1s4Ef12QpZc6fm7O6ZP/wuoq48dgQWOo7lZdrI5/Qgpv7vH8ksAlAWbT7YdHUWDKiUEjLJXI0m2Abwcm4hF//7pgXqc1QGaYp+ws7p4Uy5bVYvfsdLzSnzay5X9xWJ9ua6hFZb6NcrdrcIZ838bQPjcjl19KCUFYs0gNOTSqkQIw3/Jk1QeKNaxZzek0U8p8HryaUUAFraLholM/EpKRpPUQ==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=GCFL2/Acc9G1DT7CuYKLDJSrV8y2s032yn6jDjzLnLg=; b=QVpyOaohY1ngggLPsVqPcz32fmXCxFamB1PvHppzei5AGp7Axq1Anb3vZ9CWWmQk/df0FTmWuYbupu4OYauugmKgBQB2dyqi0bRUidHYN9tMBCfLu6sw4+jqqMxQeBsJmo+FfEir+SDEByslNbbc/PdyHmjfab+K2vdidhTU+BaD978oKhMYlo507vH5bGaopuI8VFlw/L99p7xZ/eQLhbAkZN4Zh8uGCeoydcerLNMA4P3/dEv+s1Y9mVy8vAAF2Q97h1b0sq9hqxm5CuJrEIdjKD2UFlK4f3A+tA1qBOD1YZt62l5uKpK/GCCjW8fYzB5igvjFJZVG71KLz3wwCA==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=microsoft.com; dmarc=pass action=none header.from=microsoft.com; dkim=pass header.d=microsoft.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=GCFL2/Acc9G1DT7CuYKLDJSrV8y2s032yn6jDjzLnLg=; b=ZZt5Rw7Rc1UJi1pWHjNQ7e97lj9qQGXL8kRUIZWtNe71E9hOkxCs4bV0e7ayAIOUDK1KFOlxpif1ATHZDgQ7XHn8SKXvNG8R5eAo7A512JoRG2F13Ir+Y+FKiW2wDS+No5uXKkC/nhnvs9MYs5r88uBjQzM8g546Mm68SpVlNR4=
Received: from DM6PR00MB0845.namprd00.prod.outlook.com (2603:10b6:5:1bc::23) by DM6PR00MB0683.namprd00.prod.outlook.com (2603:10b6:5:21c::7) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3278.0; Thu, 30 Jul 2020 03:05:42 +0000
Received: from DM6PR00MB0845.namprd00.prod.outlook.com ([fe80::a43a:e0bf:7bd6:f2d7]) by DM6PR00MB0845.namprd00.prod.outlook.com ([fe80::a43a:e0bf:7bd6:f2d7%6]) with mapi id 15.20.3282.000; Thu, 30 Jul 2020 03:05:42 +0000
From: Darrel Miller <Darrel.Miller@microsoft.com>
To: "dispatch@ietf.org" <dispatch@ietf.org>
Thread-Topic: [dispatch] A WG for HTTP API Building Blocks
Thread-Index: AQHWZeB5RUZzwBBfDku3ANGv5NQrr6kfLL+T
Date: Thu, 30 Jul 2020 03:05:42 +0000
Message-ID: <DM6PR00MB08455FC9C8F45CED0A416611F0700@DM6PR00MB0845.namprd00.prod.outlook.com>
References: <CAChr6SzbYQzn9HLUe4Lq23N9BGXF35NvmHZxYNV485r4D04g-w@mail.gmail.com>
In-Reply-To: <CAChr6SzbYQzn9HLUe4Lq23N9BGXF35NvmHZxYNV485r4D04g-w@mail.gmail.com>
Accept-Language: en-US
Content-Language: en-CA
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
msip_labels: MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_Enabled=True; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_SiteId=72f988bf-86f1-41af-91ab-2d7cd011db47; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_SetDate=2020-07-29T23:01:53.2150136Z; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_ContentBits=0; MSIP_Label_f42aa342-8706-4288-bd11-ebb85995028c_Method=Privileged
authentication-results: ietf.org; dkim=none (message not signed) header.d=none;ietf.org; dmarc=none action=none header.from=microsoft.com;
x-originating-ip: [69.159.101.65]
x-ms-publictraffictype: Email
x-ms-office365-filtering-ht: Tenant
x-ms-office365-filtering-correlation-id: 33af175d-feba-484d-ee3d-08d83435725a
x-ms-traffictypediagnostic: DM6PR00MB0683:
x-microsoft-antispam-prvs: <DM6PR00MB0683DD437364C847F633F276F0711@DM6PR00MB0683.namprd00.prod.outlook.com>
x-ms-oob-tlc-oobclassifiers: OLM:10000;
x-ms-exchange-senderadcheck: 1
x-microsoft-antispam: BCL:0;
x-microsoft-antispam-message-info: egDwef7VjORDbiqkta+XiwzlqqZ8dISl74kn1cb+lmBkdky2RIactbs8dhUG9zAYvZhAundC+Wf35TW69nY36VXXuiICpPukbuF9Z5rO0dKJ24Mw3gstqxdIHKSTK0RS6lzmbKm/3gbpEm8atK85HzrCTdxJtf2gPLCyeB8fJ4+OULW97lYcTGob90yNxk/3z/Tr4uYSQkJXaXKc/gbH0QV0I6/Bi8lKXNip8bQ0IX6y6gmRqvGgKU6KiadOgaXSekXK6qf2Fp3BR3jHsxyL6OXYQW6RBZ2zSdQHVLXOQB4sIPCLLmNhFTOioYCl26paSL+3guB+sJBd0cIDXwJjD9zv3kfP9Ql0YZ9JYxnkSpm5iy3Oe2ves7X6LYRMot28RIIABam1Zmb7E37iKL0Uaw==
x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DM6PR00MB0845.namprd00.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(346002)(366004)(136003)(39860400002)(396003)(376002)(9686003)(6506007)(186003)(8990500004)(53546011)(55016002)(478600001)(5660300002)(7696005)(52536014)(10290500003)(71200400001)(33656002)(26005)(316002)(966005)(66946007)(82950400001)(166002)(82960400001)(66476007)(66556008)(64756008)(66446008)(2906002)(83380400001)(76116006)(86362001)(8676002)(8936002)(6916009); DIR:OUT; SFP:1102;
x-ms-exchange-antispam-messagedata: JJkPKViNErRo1lH5LOf0V1bhPYoR+u1x/3LphVcF/fbZ04nOr2RUoVg8Hv78RpF+NG7u2g3zHxPI24NoRx1GvbFOnpQnullFl3WMmIkNCmoYR5OQJ7HgaNXEhxBTlBty1mvcgEo/NoTmB+Yp3KuHN5ePtvvntW6CFKzAtywbdYcEHP1Vnf9TMOtvABm+4k5jYfPnPsZdGVcBJ5KERq9gV6/6ffXAxQC2ZcfiikPY+9xdH2geyT3KO1u33V4khZhwXOFNQT1xgIwLsCh9ZbhjG5/dXFH7jqN/2E0iKgLz+bru+lognjVG0j3I+KL9M5+ZQ6V7fJm0MxGK2r9oh4Lv/GyRk6vDXdxDp6+Jn8SUJTEbC94qAoyok26knZ/Ze7xkRo4Vy+fCLXQoNSU4PrMwaCW/hubqKw2UILwZQmI0QmvM6hpWBt0MNqxAfa34QZk6wBz4qJoTikGI7zXSvbVMsX2s8OmQUznLncZlX5h5lHH7BPd6SkdY33Q+bATKz/8zGXWaKpLOSQ/tSKmGmLKwlf/OO+GJFDYqDkasBED+cj2YktapL5kbfwQhiZ8f57n8zug3xEr6zff+RvV3yYaZlxamehg6KbqA7dCYvkk7LT36N72drzbtYdlThFIhXu59Ctkx8tgxYGqm+eEbA3s5zQ==
x-ms-exchange-transport-forked: True
Content-Type: multipart/alternative; boundary="_000_DM6PR00MB08455FC9C8F45CED0A416611F0700DM6PR00MB0845namp_"
MIME-Version: 1.0
X-OriginatorOrg: microsoft.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-AuthSource: DM6PR00MB0845.namprd00.prod.outlook.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 33af175d-feba-484d-ee3d-08d83435725a
X-MS-Exchange-CrossTenant-originalarrivaltime: 30 Jul 2020 03:05:42.8332 (UTC)
X-MS-Exchange-CrossTenant-fromentityheader: Hosted
X-MS-Exchange-CrossTenant-id: 72f988bf-86f1-41af-91ab-2d7cd011db47
X-MS-Exchange-CrossTenant-mailboxtype: HOSTED
X-MS-Exchange-CrossTenant-userprincipalname: Ymknu2rnjv6Oh8HN/7N6scgl9fxbvzKtiFMqZG1IrYNMCg/oQJgM1wWsPU8rbMBvgLQpkBbDEOHGXWRtveQTYw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR00MB0683
Archived-At: <https://mailarchive.ietf.org/arch/msg/dispatch/gpOPmIHJ9HrOTBYg8-VHEp2FYYg>
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: Thu, 30 Jul 2020 03:05:54 -0000

Rob,

Thanks for sharing the link to the recording.  I had planned on attending the meeting on Monday but sadly did not make it.

I agree the aims of the charter are good.  A large part of my day job involves working with teams who are trying to expose HTTP APIs to our customers and are looking for guidance on how to use HTTP in a consistent way for machine 2 machine communications.

I think there are a many areas that would benefit from industry wide guidance. Some examples include:

- Long running operations that return a 202 Accepted header and reference a “status monitor” resource. This is a topic that comes up regularly.
- Resumable large file uploads is a tricky topic that if I recall was discussed at last years HTTP Workshop.
- Safe requests that require more parameters than will fit in a query string and still make it all the way to the origin server.  Many APIs have complex search requirements.  James Snell had a draft to revive the SEARCH method a few years ago.
- The current drafts around deprecated and sunset headers are a good start to help API builders evolve their APIs, but there is more work that could be done in this area.

For years, people building HTTP API frameworks have taken opinionated stances on how HTTP should be used as an application protocol in order to shield developers the nuances of HTTP. The frameworks would find solutions to missing guidance related to HTTP APIs.  This has led to a fairly significant lack of knowledge in the average developer of how HTTP can be used to build network based applications.  In my experience, the disparity between the developers building web browsers and those building applications that use HTTP client libraries directly to call HTTP APIs is huge.  It is rare to find a developer working with a HTTP API that actually understands or even is aware of chunked encoding.  And yet every developer I meet who has heard of gRPC knows all about its ability to stream payloads.

I believe a IETF HTTP API working group could deliver a significant amount of value to the industry through the creation of well informed guidance and specifications.  It is clear to me that there is a need based on the number of companies that have written their own HTTP API design guidelines to ensure consistency and correctness within their own org.  There are so many, that community members have built sites that aggregate guidelines together to try and discourage people from creating more. http://apistylebook.com/design/guidelines/

I do believe now is the right time for this effort.  The majority of large companies have recognized the need for network based APIs to be an essential part of their technology platform.  I see this regularly as part of my work with the OpenAPI Initiative. However, frustration with the inconsistent and sometimes poor use of HTTP is causing companies to look closely at more prescriptive but less ubiquitous solutions.

Darrel


From: Rob Sayre<mailto:sayrer@gmail.com>
Sent: July 29, 2020 3:43 PM
To: dispatch@ietf.org<mailto:dispatch@ietf.org>
Subject: Re: [dispatch] A WG for HTTP API Building Blocks

Hi,

Sorry to fragment the thread, but I wasn't subscribed to this list, and only saw a notice posted on the HTTP list.

I think the proposal's aims are good, but some of the suggested techniques are a bit dated. The Australian example in the presentation is a good example of this concern[1].

This kind of documentation for a JSON API is considered an anti-pattern by many. It's a prose schema. Most companies I've worked with eventually switch to something like Protocol Buffers, Thrift, etc. Or, they started working with typed queries, as in GraphQL. Larger companies tend to combine these approaches. For example, GraphQL specifies pagination[2], but large companies often return something other than JSON, so they can get 64-bit numbers and binary payloads, in a somewhat more efficient format.

Standardizing the things I've mentioned might not be possible (although I would love to settle on GraphQL + Flatbuffers...), but I think this list should at least contemplate whether the WG would be duplicating work here.

thanks,
Rob

[1] https://www.youtube.com/watch?v=KDN7SamlAn0&t=4653s<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DKDN7SamlAn0%26t%3D4653s&data=02%7C01%7Cdarrel.miller%40microsoft.com%7C37640406c64e45645da308d833f766d5%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637316485830935948&sdata=gEAxOf1Hg8ycaP8OFkU1fccPtENHxkAa7r7DoHlpgCg%3D&reserved=0>
[2] https://graphql.org/learn/pagination/<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgraphql.org%2Flearn%2Fpagination%2F&data=02%7C01%7Cdarrel.miller%40microsoft.com%7C37640406c64e45645da308d833f766d5%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637316485830940940&sdata=QdbEoaUYQXECY%2F5upyt7PiYDUTxHBKq5xig0r5IeZX4%3D&reserved=0>