Session Date/Time: 27 Jul 2023 16:30

httpapi

Summary

The httpapi working group meeting covered the status of several documents, including YAML media type registration, REST API media types, link template header field, problem details, deprecation header, and HTTP API authentication link. Discussions included whether to separate the OpenAPI media type registration from the JSON schema media type registration, specifying a value for the Item potency key header, and changes to the rate limit header specification. The group also discussed a proposal for an API catalog well-known URI, an update to byte range patch, relative JSON pointer, and web linking. Several documents were proposed for adoption, and action items were assigned to progress the work.

Key Discussion Points

REST API Media Types (OpenAPI and JSON Schema): Whether to split out the OpenAPI media type registration into its own document, separate from the JSON Schema media type registration, to follow a pattern that has worked previously. Concerns were raised about ensuring interoperability and effective use in catalogs and tooling if only registration forms are filled out.
Linked Template HTB Headerfield: Update on the document which was paused due to the title parameter that contained non ASCII characters. Now that Structured fields allow non ASCII characters, the document can continue, but there are interesting questions about how to handle other extensions in link template.
Deprecation Header: The group is looking for someone to take over the document, and has already spoke offline with someone who is interested. If nobody volunteers, it will be parked.
Item potency Key Header: Discussion on standardizing the value of the Item potency key header to enable generic clients to send it more easily. Concerns were raised about the potential for confusion and divergence if clients make different assumptions about its behavior.
Rate Limit Header: Presentation of proposed changes to the rate limit header specification, including introducing an identifier for the policy and using a structured field item to identify the policy. Questions about the expected consuming use case of the data and whether it might expose too much information were addressed.
API Catalog: Presentation of an API catalog well-known URI to help discover APIs, their functions, and locations. Discussions involved the format of the catalog, intended use cases, and the possibility of reusing existing formats and the question of what link relations should be supported.
Byte Range Patch: Review of updates to the byte range patch document, which defines a media type for patching files. Discussion about how it related to resumable uploads and if it caused more complications.
Relative JSON Pointer: Overview of relative JSON Pointer and its use cases, including JSON schema annotations. One of the discussion was the issue of resolving without a documentary.
Web Linking: Presentation of predefined target attributes that either of link relation can opt into to get a set as a well defined basis for what they need to do. There was interest in this and the meeting asked Mark to post a new version.

Decisions and Action Items

REST API Media Types: Continue conversations on the GitHub issue, taking into account Roberto's concerns, to decide whether to proceed in parallel or use the Mark Nottingham shortcut (media man working group).
HTTP API Authentication Link: Request an early review from the security area (e.g., OAuth). Chairs will take action.
Item potency Key Header: Continue working with the editors of the draft, David Benjamin and authors, to refine the wording and address concerns raised.
Deprecation Header: Continue the conversation with Everett and ask on the list if there is no other interest and if not it will be parked.
API Catalog: Perform a formal call for adoption on the mailing list.
Byte Range Patch: Chairs will discuss Byte Range Patch and Resumable Uploads and HTTP test to figure out if things need to be moved. After they will send a note to the list.
Relative JSON Pointer: Henry to take it to the list.
Web Linking: Post for adoption on the list. Ask if people are interested for Mark to do more work.

Next Steps

Follow up on action items.
Continue discussions on mailing list.
Prepare adoption calls for appropriate drafts.