Minutes IETF117: httpapi: Thu 16:30
minutes-117-httpapi-202307271630-00

HTTPAPI Meeting Minutes - 27 July 2023
Chairs: Darrel Miller, Rich Salz
Notetaker: Ankshit Jain, Travis Langston

Agenda Bashing

WG Documents - Status Update

YAML Media Type registration
Roberto Polli (RP): If we want media type registration to be effective
and interoperable,
Mark Nottingham (MN): Has a draft in media man working group this
afternoon allows community efforts (ie open source projects) to register
media types without writing an RFC.
Darrel Miller (DM): As an individual: addressing Roberto's concern - one
of issues with YAML media type was there were multiple different
fragment identifiers possible using anchors, something that's not
possible using OpenAPI.
Henry Andrews (HA): OpenAPI 3.1 - fragments in JSON Schema, open up to
unicode instead of ASCII, json schema hasn't substantially changed.
DM: Have conversations taking into account Roberto's concern - do we do
these in parallel or take MN's shortcut?
HA: Can define handoff to schema without RFC.

Link-Template HTTP Header Field
MN: on pause for a while, includes things like title parameter, waiting
to see if HTTP working group will publish a revision of structured
fields that allows non ASCII characters, which it now has.

Hans-Jörg Happel (HH): Missing weblinking realm attribute.
MN: URI Template for user accounts
HH: Use case is different. Programmatic + User access. Can continue this
offline.
MN: Use case is create a tool to go find template and create URIs from
it - in scope. Look at pages, derive what variables in URIs are -
probably not in scope.
HH: Site owner - might not be able to only put this in the headers.
Might be interesting to have an alternative way to use the weblinking
stuff.
MN: Doesn't disagree, but we don't control HTML. Create an issue, work
there because it's an interesting use case.

Problem Details
MN: Minor details being worked out for RFC

Deprecation Header
DM and Rich Salz (RS): Looking for people to move the draft forward, or
park it for now.
Evert Pot (EP): Interested in this header, thinks it is useful,
volunteering to push it through.

draft-ietf-httpapi-authentication-link
EP: No updates, looking for next steps
DM: Who in the room has read the draft? Request - if you're interested
read it and provide feedback.
RS: Can ask someone from security area to provide feedback

WG Document Presentations

The Idempotency-Key HTTP Header Field
David Benjamin (DB): Presenter : Draft specified name of the header, but
content + syntax could be detailed. Thinks browsers can limit the number
of times Host is retransmitted. Well defined syntax can help other APIs
built over HTTP. Asking to standardize a value.
DM: Asking for feedback on particular wording.
No objections on the wording in the room.
Austin Wright (AW): No objections, asking about option of publishing a
method, not HTTP method, more general.
DM: Add comment to issue, continue conversation.
Bhavana (BH): Does this mean that methods that guarantee idempotency and
those that don't can both carry this item?
RS: Not changing the HTTP semantics - not changing behavior of GET for
example. Way for the server to tell the client to not retransmit if this
key is present.
BH: Worried it will cause more problems - some browsers retransmit POST,
some don't. Worried about adding complexity, divergence.
DB: Every browser retries POST, causes race conditions
BH: Tried to solve the problem but no solution yet

Aaron Parecki (AP): Commenting on authentication link, wondering who is
the consumer of that header? If there's not an API consumer, what is
purpose of the header in this WG?
RS: Post the question to the list
DM: Reasonable for a native client to consume it?
AP: Info on intended use seems sparse in the draft right now.

Rate Limit Headers
DM: (Presenter) Working with Roberto on this draft (currently draft 7).
Reduce RateLimit header to a single header. Limit units should be same
for a resource, they can be different for different resourses.
Proposal 1: introduce an identifier for the policy: "protection" and
"quota".
Proposal 2: structured field item to identify the policy with parameters
on policy.
Looking for feedback on proposals.
RS: Any preferences between 1 and 2?
AP: What is expected consuming use case? What should the client do when
it sees this header?
DM: Back off - ability for client to control its own rate-limiting,
avoid service telling it not to continue.
AP: Which policy is being violated?
DM: In theory, it can adjust types of requests it makes so as to
continue delivering value to the consumer without getting blocked. Still
using original example of being throttled based on number of requests.
But can imagine another policy based on bandwidth - so can avoid getting
throttled on that policy while continuing to make requests.
AP: Risk of server exposing information it doesn't want to expose. What
about hidden policies? What if the server wants to tell the client to
back off but not tell why? Names like protection, quota reveals too much
information. Can we make it opaque?
DM: Fair feedback, but server is in complete control of how it names
those policies, free to make them as obscure as it chooses. Customers
are asking for APIs that explain exactly why they're being throttled.
AP: What's the purpose of naming them if only values are being provided?

DM: Needs to be out of band communication to say what is the unit of
protection and unit of quota. Want to encode the units here as well.
HH: Finds it useful and interesting. Willing to provide review. Can
clients request raised values? Which layer does these values come from?

DM: It's an identifier, can structure to convey as much or as little
info as you want. Can discuss whether the spec should define additional
semantics.
MN: Name could be arbitrary. Need to consider security while naming.
Some people won't put every policy in header and that's ok, can be as
descriptive as you want to. Doesn't expect client will automatically
agree to reduce limits based on this header. But this could come up in
dev tools and dashboards. Talked about different units, but they're not
actually in the structures we're talking about here.
DM: Open issue. Rate limit policy allows additional parameters for
extensability. How to prevent naming conflicts? Same issue as JSON
extensions.
RP: Problem is receiver should make a match between the rate limit aand
the policy. Just the rate limit might not be enough, provide enough
information for processing the values. If we need to always make the
match between policy and limit, better to provide all the information in
one field. If possible to just consume only the rate limit without
looking at policy field, then it's fine having 2. Prefers policy 2.
Security considerations - policy information shouldn't expose
infrastructure information.
DM: Identifier requires additional security considerations. Not
significant but there is some risk. Important thing about having the 2
fields is the policy contains information that is static. No real clear
guidance as to when to send the ratelimit-policy header. Separate two
fields for perf reasons, might have large part that never changes.

New Docs:
api-catalog
Kevin Smith (KS): solve the problem of api discovery and usage. Proposes
a well known URL for the api-catalog. linkset to automate the discovery.
Discuss and agree on the link header binding and security
considerations.
RP: Likes the proposal. Suggests to look at the identity world to reuse
exchanging URL endpoints.
KS: Will consider.
Alex Chernyakhovsky (AC): Questions about intended use case for this.
Knowing what endpoints are is half the battle. Potential value here, but
missing connection to some real world use cases right now.
KS: Generic use case is the idea. Once API is listed, more information
can be obtained from provided endpoint.
DM: We build tooling that does client generation, oneof features is to
go searching for API - because no standard place where people put
OpenAPI files, having this ability to discover the OpenAPI files would
help. Should we specify in the document the supported relations, or be
open to allowing people to add any link relation?
KS: Should be. Sees no reason to restrict link relation.
DM: Asking for sentiment in room about adoption. Number of thumbs up,
moderate interest from some enthusiastic people. Take it to list for
formal call for adoption.

Byte Range PATCH:
AW: Presenting
Guoye Zhang (GZ): One of editors of resumable upload draft, would like
to see it adopted. Don't think it's possible to change syntax of
Content-Range - compatibility issues with existing implementations.
Wants slightly more defined semantics of the PATCH operation. Can
increase the implementation complexity. Thinks application's byte ranges
is a very generic thing that can support any multipart request or
response - should be a separate document, useful outside byte ranges.
Happy to collaborate on this.
AW: Overloading the content range is new. Special case if it uses the
proposed syntax. Can provide different header name if objection on
philosophical grounds. Clients could send a header, outside the scope of
the document. Would love to see HTTP WG take this up.
Michael Toomim (MT): Appreciates the work. Similarities to collaborative
editing. Design decision to handle opportunisitic patches. Alternate:
Ask server if it supports Content Range in PUT. Adds latency but doesn't
impact much due to multi-part body.
AW: By using media type in a PATCH request, you're asking both questions
- does server support this, and can you apply this patch. Not something
you can deploy across an entire origin server, need to look it up for
each resource. Trying to avoid additional round trips, reason for adding
a new media type.
MT: Can discuss and solve the disagreement over the design decision on
the list. Leans to the other side of the decision.
Marius Kleidl (MK): Overlap with resumable uploads on the byte range. In
favor of adoption. Wants to talk about collaboration and reuse.
AW: This supports a subset of resumable requests - uploading with a PUT
request, can resume with PATCH. Simpler than generic case of resuming
with POST request. Should be able to talk about this patch outside fo
the context of an HTTP message.
MK: Agrees with the reasoning.
DM: Is it a problem to add this in HTTPAPI while resumable uploads is in
HTTPBIS?
MN: Worried about this as well. Interesting work, should go forward, but
coordination raises a lot of interesting questions, likely not problems.
Chairs should get together and chat.
DM: Will have conversation, bring thoughts to mailing list to weigh in
on.
RS: Any opposition to us working on some subset, anyone opposed to
adoption? No, will take to list.

Relative JSON Pointer:
Henry Andrews (HA): Presenting
DM: Asks if anyone has used this before? No comments or objections.
HA: Spec has existed for years. Nothing super complex here. Uses this a
lot. Other uses cases - schema with an annotation format that will take
the data structure and translate it into database queries. Has found us
cases, there are implementations so that's not a problem, someone has
used it.
MT: Not using JSON pointers. Working on JSON range unit - Useful for
collaborative editing. Thinking about incorporating relative JSON, happy
to collaborate.
HA: Thinks it sounds interesting.
DM: Does JSON path support a slice of the array?
HA: Doesn't know, uses relative JSON pointer because it's so much easier
to do.
Chairs: Will take it to the list.

Link Hints:
MN: Presenting
Looking for adopters.
RS: Asks if anyone has read the document? No, so take a pass and then
consider it. Ask MN to keep working on this and then confirm on the
list.
EP: Asks MN to keep working on it. Finds it useful.
MT: If server supports link requests?
MN: There because there's an accept-ranges header in HTTP.
MT: Use cases?
MN: Wrote it down because he thought it was a reasonable idea.
EP: Endpoints should describe data as much as possible. Describe what
all features are available to hint the rendering. Ex: forms,
documentation.
MT: Helpful.
HH: Sounds similar to OpenAPI in general. Might help to set this in
relation, describe the use case.
MN: It's not a format, but a vocabulary of attributes that you can put
on links.
HH: Sounds like API Spec.
DM: What is the limit for links vs pointing to the operations?
HA: Did add target hints when working on hyperschema. Seems useful
because it was useful there.
MN: Not something that'll be used directly by someone working on an API,
will be used when working on link relation specs, format specs. Should
be easy to agree on. Low hanging fruit.
HA: Decomposing is helpful.
RS: Asks if enough support to make it worthwhile to proceed, or look at
list?
MN: Happy to put work into it if people feel it's worth it, only way to
do that is call for adoption.
Chairs: Will ask for adoption on list. Any other business? No.

End of meeting.