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

From: Rob Sayre <[email-masked]>
Date: Wed, 29 Jul 2020 12:41:10 -0700

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/

---

From: Darrel Miller <[email-masked]>
Date: Thu, 30 Jul 2020 03:05:42 +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:[email-masked]>
Sent: July 29, 2020 3:43 PM
To: [email-masked]<mailto:[email-masked]>
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>

---

From: Rob Sayre <[email-masked]>
Date: Wed, 29 Jul 2020 20:18:31 -0700

On Wed, Jul 29, 2020 at 8:06 PM Darrel Miller <Darrel.Miller=
[email-masked]> wrote:

>
> - Long running operations that return a 202 Accepted header and reference
> a “status monitor” resource. This is a topic that comes up regularly.
>

Thanks for the thoughtful response, most of which can be better answered by
others.

On these two quoted related topics, I can answer. You just want something
like this: https://aws.amazon.com/blogs/aws/amazon-s3-multipart-upload/

I think the AWS minimum chunk size is too large, but otherwise this API or
something like it (there are many clones), would be fine.

thanks,
Rob

---

From: mca <[email-masked]>
Date: Thu, 30 Jul 2020 09:23:06 -0400

I was unable to attend so please pardon my digressions and miscues -- feel
free to point me in the right direction.

Per points one and two in the proposed chapter, I think there are a a few
possible sources of content for definitions/specs related to
machine-to-machine APIs.

- Subbu Alamaraju's "RESTful Web Services Cookbook" [1] identifies a
collection of recipes to solve common API problems over HTTP and might be
fertile ground for defining headers, bodies and a handful of common
practices.
- My talk/slides on Hypermedia Patterns [2] has a handful of elements that
could be improved over HTTP w/ some body/header/status work
- I assume there are others, too

As for point three, I'd also like to see the group continue to focus on
best practices and steer clear of attempting to define API sets to solve
particular problems.

[1]
https://books.google.com/books/about/RESTful_Web_Services_Cookbook.html?id=ed5ml0T3zyIC
[2] http://amundsen.com/talks/2017-04-craftconf/index.html

Mike Amundsen

*APIs, Microservices, and Digital Transformation*
7310 Turfway Rd. Suite 550, Florence, KY, 41042

*+1.859.372.6517*
https://zoom.us/j/8593726715
http://linkedin.com/in/mamund
http://g.mamund.com/meetme
http://training.amundsen.com
http://twitter.com/mamund

On Wed, Jul 29, 2020 at 11:19 PM Rob Sayre <[email-masked]> wrote:

> Thanks for the thoughtful response, most of which can be better answered
> by others.
>
> something like it (there are many clones), would be fine..
>
> thanks,
> Rob
> _______________________________________________
> dispatch mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/dispatch
>