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

[Rob Sayre <[e-mail]>]

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
[2] https://graphql.org/learn/pagination/