**Session Date/Time:** 29 Jul 2022 14:00 # httpapi ## Summary The httpapi working group convened to discuss several active drafts. Key discussions revolved around the *Rate Limit* headers, where the working group did not reach consensus on consolidating three separate headers into a single structured field, despite editor investigation. For *API Media Types*, the working group decided against including a normative YAML to JSON conversion algorithm, deeming it out of scope. The JSON-LD context appendix for *HTTP Problem Details (7807bis)* was also removed due to complexity and scope concerns, clearing the path for its publication. Finally, a significant portion of the session focused on the *Deprecation* header, with a proposal to introduce a new, consolidated *Lifecycle* header using structured fields to encompass deprecation, sunset, and other API lifecycle stages. While enthusiasm for this was noted, formal consensus was not achieved. ## Key Discussion Points * **Rate Limit Headers (draft-ietf-httpapi-rate-limit-headers)** * **Goal:** Communicate service limits to clients, consolidate existing practices, and avoid header proliferation. Introduced `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy` as structured fields. * **Editor's Stance (Roberto):** Editors decided against combining these into a single structured field, as requested by some WG members. * **Rationale:** Current implementations (10+ years) widely use separate integer-valued fields; implementers found combined fields confusing; structured field parsers are not yet widely available in the current API ecosystem. The primary goal is to consolidate existing practice, not to force new syntax without operational experience. * **Working Group Concerns (Mark Nottingham, Martin Thomson):** Discomfort with editor decisions based on unshared data. Aesthetically, three separate headers are repetitive. If specified as structured fields, but appearing as simple integers, it creates an "attractive nuisance" that could lead to parsing errors with future extensions. A single, atomic unit would be more efficient and easier to process. * **Poll Results:** A poll on combining the fields into one structured field (vs. keeping three separate headers) showed **no consensus** (7 for editor's decision / 3 headers, 6 against / 1 header, out of 13 voters). * **Media Types for API Specifications (draft-ietf-httpapi-media-type-registration)** * **Goal:** Register media types for OpenAPI, JSON Schema, etc., to improve interoperability and content negotiation. Focus on `application/yaml` and `application/plus+yaml`. * **Fragment Identifier for `+yaml`:** Discussion on whether `plus+yaml` media types should be required to use the same fragment identifier as `application/yaml`. * **Editors' View:** Forcing this would break existing implementations (e.g., `application/schema+yaml` already defines its own). RFC 6838 does not require `+suffix` types to share the base type's fragment identifier. Flexibility for new types to define their own is preferred. * **Mark Nottingham:** Common pattern is for `+suffix` types to default to the base type's fragment identifier, but allow opting out. * **Normative YAML to JSON Conversion (Issue 59):** A request from the W3C YAML-LD working group to include a normative algorithm for converting YAML to JSON. * **Working Group Position (Chairs, Mark Nottingham):** This is complex, potentially outside the working group's charter, would delay the draft, and would be a significant scope creep for a media type registration document. * **HTTP Problem Details (RFC 7807bis / draft-ietf-httpapi-rfc7807bis)** * The document has passed working group last call. * **JSON-LD Context Appendix:** An open question was whether to include a JSON-LD context as a non-normative appendix. * **Discussion (Eric, Mark Nottingham):** JSON-LD involves mapping JSON to RDF, which requires settling on an RDF vocabulary. This is a complex discussion belonging more to the RDF community, not the httpapi WG, and would be difficult to resolve in time for an immutable RFC. * **Deprecation Header (draft-ietf-httpapi-deprecation)** * **Current State (Eric):** The draft aligns syntactically with the `Sunset` header (uses HTTP-date format, not a structured field), for consistency. * **Proposal for `Lifecycle` Header (Eric, Mark Nottingham):** A new, generic `Lifecycle` header could encompass `Sunset`, `Deprecation`, and potentially other API lifecycle stages (e.g., experimental). This would use structured fields. * **Pros:** Single place for API status, consistent syntax (structured fields), naturally extensible. * **Cons (Eric):** Would mean starting from scratch, might take considerable time (1-2 years), and would obsolete the existing `Sunset` RFC. * **Structured Fields Date Type (Mark Nottingham):** Discussion hijacked to gather feedback on adding a `date` type to structured fields (e.g., `@` + integer epoch vs. ISO date string). This could make structured fields more attractive for deprecation/lifecycle. * **Poll Results:** A poll on exploring a unified `Lifecycle` header as an alternative to separate `Sunset` and `Deprecation` headers showed **enthusiasm but not consensus** (9 for, 3 against, out of 12 voters). * **Idempotency-Key Header (draft-ietf-httpapi-idempotency)** * Author (Sanjay) was not present. * **Status (Eric):** No formal blockers, but not ready for WG Last Call; needs a re-read and review. * **Link Template (draft-ietf-httpapi-link-template)** * **Status (Mark Nottingham):** Similar discussions regarding consistency with existing `Link` headers. Will reuse structured field syntax from the retrofit draft. Will explore allowing URI templates in the `anchor` parameter. This addresses a common issue in the OpenAPI world. ## Decisions and Action Items * **Rate Limit Headers:** * **Decision:** No consensus was reached on combining the `RateLimit-` headers into a single structured field. * **Action Item:** Discussion on this issue (pull request 65) will continue on the mailing list and GitHub. API community members are encouraged to participate. * **Media Types for API Specifications:** * **Decision:** The request to include a normative YAML to JSON conversion algorithm (Issue 59) is **out of scope** for this working group's charter. The related pull request will be closed. * **Action Item:** Discussion on the fragment identifier rules for `plus+yaml` media types will continue on the mailing list. * **HTTP Problem Details (RFC 7807bis):** * **Decision:** The JSON-LD context appendix will **not** be included in the document. * **Action Item:** The document will proceed towards publication without the JSON-LD context appendix. * **Deprecation Header:** * **Decision:** No consensus was reached on moving to a unified `Lifecycle` header, despite enthusiasm in the room poll. * **Action Item:** Discussion on the `Lifecycle` header proposal will be taken to the mailing list for broader feedback. Eric to initiate this. * **Idempotency-Key Header:** * **Action Item:** Eric to reach out to Sanjay for updates and to assess readiness for WG Last Call. * **Link Template:** * **Action Item:** Mark Nottingham will prepare a Pull Request to update the draft to use structured fields. * **General:** * **Announcement:** The `Link Set` document (RFC 9264) has been successfully published, marking the first RFC from this working group. ## Next Steps * Continued discussion on the `RateLimit-` headers and `plus+yaml` fragment identifiers on the working group mailing list and GitHub. * Eric to post a summary and solicit further feedback on the `Lifecycle` header proposal to the mailing list. * Mark Nottingham to submit a PR for the `Link Template` draft using structured fields. * Eric to coordinate with Sanjay regarding the `Idempotency-Key` draft. * The chairs will proceed with the publication of `HTTP Problem Details (7807bis)` without the JSON-LD context appendix.