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

[Brian Rosen <[e-mail]>]

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 <[e-mail]> 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 <[e-mail] <mailto:[e-mail]>> 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/ <https://www.mnot.net/>
> 
> _______________________________________________
> dispatch mailing list
> [e-mail] <mailto:[e-mail]>
> https://www.ietf.org/mailman/listinfo/dispatch <https://www.ietf.org/mailman/listinfo/dispatch>
> _______________________________________________
> dispatch mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/dispatch