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

Rob Sayre <> Wed, 29 July 2020 19:41 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 5631A3A0E8C for <>; Wed, 29 Jul 2020 12:41:24 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -2.097
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: (amavisd-new); dkim=pass (2048-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id hfoWwL7p0YT8 for <>; Wed, 29 Jul 2020 12:41:23 -0700 (PDT)
Received: from ( [IPv6:2607:f8b0:4864:20::143]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id D26063A0E52 for <>; Wed, 29 Jul 2020 12:41:22 -0700 (PDT)
Received: by with SMTP id c16so8661526ils.8 for <>; Wed, 29 Jul 2020 12:41:22 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=mime-version:from:date:message-id:subject:to; bh=bXazkk+jo9wtylist2vRQgwsUaKPw6GG1jsxNoEDD/g=; b=D60KhbRKI8+fDrM0+ItxEvMXqbLZjXlKnvk2+UCvp30V0Daj7EdIJf3Gx3jfMKHYZr PUfaB6OBHjsOoFJwnRgFB1Ri9NthO2/ZSHro451WIiw1GbISh7LxrnshYFeegDu6MeAX NBaib+jakiWM3bdOuIniM8wXCuXTr930pptxRu9fWOZtgt5d4t1U/ofleGVmeLQmV72S 58s7iH04HEtv324Cg/V5cHE5+Aq3VChP2YdT/kC+FFK5n8QajUpHO6Bv90vODlpU7ZjK B8c0euK3BmVpBjRP+F/sTTaoOR4+2o+F0EYTaSECfZ9fbqkYObpbBpXmTzpCPYFIh+xU FnjQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; bh=bXazkk+jo9wtylist2vRQgwsUaKPw6GG1jsxNoEDD/g=; b=gIteNpsPZqy40sr5nddj8ylcon9Z9uKJiyftNNcshjfwFfD+qEXZ4+LrMGPCbxLTn0 SmU6n9yMFvx5ns0KzYrBg8TRFVBGehqu0p/OI5zFhD9DPchLTTzB+1UZmPr12WYcoLZ0 KEzg9KNo3V6E8PTFvrhhHD2jVhNsvCMWr3efGFc/CNvljP2HxfxLpIsZpESFdx9LMF+K j1j3W2U+6XmxP8t0cCAnDUeU+tHzmV12mT0NoJGSSB1yFys7sc8mUtDfmgbep9lmvcCk KK+fvz7NGi+LIloFK2Ihe73huWWlrb+Cf3REgm9spxTGPspynifgYyHx1iG4vXSWIRS1 8CdA==
X-Gm-Message-State: AOAM530vmsLabAszeoOFPIXYXE8AmNCDdObee6rkFexiLAnWrHYHqm7J BaworWeTouTYHlBoYsi0UwP5SmbXb45e0YO4HBRUx/6P72M=
X-Google-Smtp-Source: ABdhPJxOhE3kpmpAHA4n3axhkcxrdDpHtRNu0VATP+KJdhOWrUoqFlPIOYXznEcCPu9UWAOLzp2oQGBbv16qEhseQRo=
X-Received: by 2002:a92:4444:: with SMTP id a4mr1478789ilm.49.1596051681664; Wed, 29 Jul 2020 12:41:21 -0700 (PDT)
MIME-Version: 1.0
From: Rob Sayre <>
Date: Wed, 29 Jul 2020 12:41:10 -0700
Message-ID: <>
Content-Type: multipart/alternative; boundary="00000000000087628b05ab99bd67"
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: Wed, 29 Jul 2020 19:41:24 -0000


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.