Session Date/Time: 12 Nov 2021 12:00

httpapi

Summary

The httpapi working group convened to discuss the status of several drafts and consider new work. Key outcomes include the Link Set draft moving to Working Group Last Call (WGLC), positive feedback for Linked Templates leading to a call for adoption, and updates on Problem Details for HTTP APIs (RFC 7807bis), Rate Limit Headers, Deprecation Header, and Idempotency-Key drafts. A potential new work item, Health Check API, was introduced and garnered interest, but chairs emphasized prioritizing existing drafts.

Meeting Logistics

Chairs: Rich Salz, Darryl Lascar
Minute Taker: Braun Gwanda (notes.ietf.org/notes-ietf-112-httpapi)
Note Well: Standard IETF Note Well was reviewed, emphasizing IPR, privacy, and respectful conduct.
Blue Sheets: Automatically generated by Meetecho sign-in.
Online Meeting Tips: Mute mics, turn off video when not speaking, use headsets.

Key Discussion Points

Query Method (draft-ietf-httpbis-safe-method-with-body)

Presenter: Mark Nottingham
Overview: A new HTTP method, QUERY, in the httpbis WG, allows safe, idempotent, and potentially cacheable requests to include a body. This addresses use cases where GET with a body is desired (e.g., long query parameters, data requiring encoding in URLs).
Semantics: Similar to GET but with a request body.
Caching: The latest draft introduces caching semantics.
Body Format: The method itself does not define the format of the query body, leaving it to applications (similar to PATCH).
Use Cases: Identified for HTTP APIs, such as ElasticSearch.
Feedback: Requested from API developers.
ACME: Suggested for potential use by ACME (POST-as-GET semantics).
Head Method: Question raised about a corresponding HEAD method for QUERY; discussion points to complexities with HEAD and potential alternatives like a request header for a "dry run".

Linked Templates (draft-nottingham-linked-templates)

Presenter: Mark Nottingham
Overview: Proposal to allow URI templates (RFC 6570) within Link header fields, enabling generative APIs where clients can construct new URIs based on provided templates.
Benefits: Reduces redundant links in large lists (e.g., a list of resources, each needing a self-link or action links).
Key Issue: Clarification needed for var-base (a mechanism for namespacing URI template variables).
Syntax: Discussion on whether to use structured headers (structured fields) for new link syntax instead of duplicating existing Link header format.
Interest: Strong interest expressed by participants, with real-world use cases (e.g., GS1 Digital Link) identified.

Link Set (draft-ietf-httpapi-linkset)

Presenter: Eric Wilde
Overview: Defines a way to represent HTTP Link header fields as a standalone resource.
Media Types: Defines two media types: one using RFC 8288 link syntax, and another JSON-based representation.
Maturity: The draft has been under development for a significant period (17 versions).
Status: All 26 GitHub issues have been addressed and closed. No open issues.
Implementations: Already in use by GS1 Digital Link and Fair Signposting Profile Specification.
Recent Updates (v5): Added support for profiles, newline characters in RFC 8288 syntax for readability, extensibility model work, and JSON-LD mapping updates.
JSON-LD Challenge: Acknowledged an incompatibility when mapping registered IETF link relation types (strings) to RDF, which requires URIs as identifiers. This is an inherent limitation not specific to the draft.
Readiness: Considered ready for Working Group Last Call.

Problem Details for HTTP APIs (RFC 7807bis) (draft-ietf-httpapi-rfc7807bis)

Presenters: Darryl Lascar, Mark Nottingham, Sanjay P. Rai, Eric Wilde
Warnings Integration: Discussion around integrating warnings. The consensus was to punt this to a future or separate specification; the issue was closed.
Multiple Problems:
- Context: How to represent multiple distinct problem details within a single response.
- Approach: Documenting examples of using extension members (e.g., a causes array) within the problem detail object.
- Guidance: Need for more nuanced guidance on different classes of multiple problems (e.g., multiple instances of the same error type vs. multiple different error types) and appropriate HTTP status codes (e.g., 400 vs. 207 Multi-Status).
- PR: Sanjay Rai has an open Pull Request for examples.
Registered Problem Types: Open question whether to define and register common problem types (e.g., "multiple errors," "validation error") within this document or in a follow-up. This is a non-trivial design task.

Rate Limit Headers (draft-ietf-httpapi-ratelimit-headers)

Presenter: Darryl Lascar (representing Roberto Polli)
Overview: Standardizing common rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset).
Naming: Discussion on shortening header names (e.g., RL-). Current practice uses X- headers, so a new standard name will break compatibility anyway.
Throttling Scope: Importance of defining how rate limits apply (e.g., per resource, per site, per user). Suggestion to define a vocabulary of scopes.
Header Dependencies: Ongoing discussion about whether all three headers are mandatory or if they can be used independently.
Structured Fields: Suggested use of structured fields, especially for multiple quotas (e.g., "100 requests in 10 minutes, 10,000 requests in 1 hour").

Deprecation Header (draft-ietf-httpapi-deprecation-header)

Presenter: Eric Wilde, Darryl Lascar, Sanjay P. Rai
Overview: A header field (Deprecation) to signal that a resource is deprecated, similar to Sunset header.
Status: No new version since last meeting; 6 open issues remain.
Scope: Discussion on whether deprecation applies to the entire resource or to fine-grained elements within a representation. Consensus leans towards resource-level due to the complexity of addressing sub-elements via an HTTP header.
Redirect: Example of redirecting to a new location as part of deprecation.
Design Choice: Discussion on using a boolean value (like OpenAPI) versus a date (like Sunset) to indicate deprecation. Mark Nottingham suggested using a date where a past date implies deprecation, simplifying programming language mappings.

Idempotency-Key (draft-ietf-httpapi-idempotency-key)

Presenter: Sanjay P. Rai, Eric Wilde
Overview: A header to enable clients to safely retry requests without unintended side effects.
Status: No new version since last meeting.
Structured Fields: Suggestion to adopt structured fields for the header.
Comparison with Oasis Repeatable Requests: Oasis spec has a broader scope (including correlation keys, more server-side burden). The group leans towards keeping Idempotency-Key focused on the simpler, widely implemented idempotency use case, with potential for future extensions if demand arises.
Appendix: Request to add an appendix explaining the relationship to conditional requests; generally supported.

Potential New Work Item: Health Check API (draft-richardson-health-check)

Presenter: Mark Nottingham, Sanjay P. Rai, Eric Wilde, Darryl Lascar
Overview: Proposal to standardize a common API for health checks, addressing a pervasive pattern in API ecosystems.
Repository: Mark Nottingham created a GitHub repo for general httpapi discussions, including this idea.
Benefits: Provides a standardized building block for health checks, promotes another semantically rich media type (like HTTP Problem).
Adoption Concerns: Sanjay P. Rai questioned current adoption by popular enterprise frameworks (e.g., Spring Boot).
Working Group Capacity: Chairs expressed reluctance to adopt new drafts until existing ones are closer to completion, aligning with the working group's charter and IESG expectations to demonstrate functioning by shipping documents.
Author Interest: Irakli Nadareishvili (author) is interested in joining if the group takes on the draft.
Charter Review: The Area Director (Francesca Palombini) noted the charter requires assessing the group's functioning and plans to have an informal discussion with the IESG on this.

Decisions and Action Items

Link Set (draft-ietf-httpapi-linkset):
- Decision: Will proceed to Working Group Last Call (WGLC).
- Action: Eric Wilde to publish version 6 (v6) with minor editorial changes.
- Action: Chairs to initiate a 2-week WGLC on the mailing list for v6 of the draft.
- Action: Rich Salz to prepare the shepherd write-up after WGLC.
Linked Templates (draft-nottingham-linked-templates):
- Decision: Working group expressed interest in adopting this draft.
- Action: Chairs will confirm a Call for Adoption on the mailing list.
Problem Details for HTTP APIs (RFC 7807bis):
- Action: Sanjay P. Rai to update the Pull Request for multiple problems with clearer examples and cautioning text.
- Action: Mark Nottingham to contribute text on nuanced guidance for different multiple status cases (e.g., 207 Multi-Status usage).
Query Method (draft-ietf-httpbis-safe-method-with-body):
- Action: Eric Wilde to open an issue in the httpbis working group repository regarding the potential use case for ACME's "POST-as-GET" pattern.
Health Check API (Potential Work Item):
- Action: Chairs to assess working group capacity to take on new drafts and coordinate with Irakli Nadareishvili.
Working Group Functioning:
- Action: Francesca Palombini (AD) will have an informal discussion with the IESG regarding the working group's functioning, as required by the charter.

Next Steps

Issue Working Group Last Call for Link Set (version 6).
Issue a Call for Adoption for Linked Templates.
Continue active work and discussion on open issues for Problem Details bis, Rate Limit Headers, Deprecation Header, and Idempotency-Key drafts.
Chairs to internally discuss the feasibility of adopting the Health Check API draft given current work priorities and working group charter requirements.
Chairs to discuss holding interims, potentially coordinating with other API-related working groups (e.g., W3C, OpenAPI initiatives) to foster broader community engagement.
Participants are encouraged to engage on GitHub issues for all active drafts and contribute to discussions in the httpapi GitHub discussion repo for potential new work items.