Deep dive: Swift HTTP APIs — how we got here (25 min)
Short presentation, then discussion
The design journey
Framing the open HTTP API issues
Community agenda items and open discussion (as time permits)
Wrap-up and action items (5 min)
Propose an agenda item
We'd love the agenda to reflect what the community wants to discuss. Please reply to this thread with topics you'd like to cover, ideally with a sentence or two of context and roughly how much time you think it needs. To keep the meeting focused, we'll include some agenda topics from the replies received for discussion as time permits and include anything else in the list of potential topics for future meetings.
A few notes so the meeting stays productive with a larger group:
Most decisions happen asynchronously on the forums, Slack, and GitHub. The meeting is for discussion and alignment, so you can participate fully asynchronously if you wish or if you cannot attend a particular timeslot.
We'll use a raised-hand queue and chat for questions and discussions. Please take note of your position in the queue and try to avoid collisions with others when speaking.
We'll post the notes from the meeting here on the forums afterwards. Note that we're piloting AI note-taking tools but won't be recording the meeting, and you can ask us to turn them off at any time.
We follow the Swift Code of Conduct. This is a public meeting, so please keep discussion to public, non-confidential topics.
The meeting featured a deep dive into the evolution of the Swift HTTP APIs, outlining key design decisions and open questions around restartable bodies and client configuration. The group also reviewed an API sketch for IP address types, discussing the use of enums and the process for evolving APIs within the forthcoming swift-network-types repository. Action items were set to advance dependencies like async streaming and to formally shepherd the HTTP API design discussions.
Notes
Swift Network Types Repository Update
The request was approved by the ESG and has been forwarded to the core team for review.
The group plans to start collaborating on IP address and port types via small, incremental pull requests as soon as the repository is created.
Repository Mechanics and API Evolution
The group discussed the process for contributing to the new repository. It will have designated code owners and will be open to contributions from anyone.
New APIs will be introduced as experimental and go through the formal Swift Evolution process to become stable. There is no near-term plan for a major version release.
There was a discussion of the mechanism for marking APIs as experimental. Compiler traits were suggested, but there were concerns about tooling support. Underscored modules were raised as an alternative, in the pattern used by SwiftNIO.
IP Address and Port Types Proposal Review
The group reviewed an API sketch for IP address types that uses enums and avoids generics.
There was discussion of an enum to represent an “any IP address” type (IPv4 or IPv6). Concerns were raised about future-proofing (for example, a hypothetical IPv8), and the current view is that the existing IP versions are stable enough for this to be a reasonable trade-off.
The group debated the ideal layer at which to introduce enums, with a preference for starting with concrete struct types and introducing enums at the endpoint level to handle different address families.
The general direction is to aim for a single, well-placed enum in the type hierarchy rather than sprinkling them throughout.
HTTP API Deep Dive (presentation by Guoye)
Guoye presented the history and design evolution of the Swift HTTP APIs, an effort spanning multiple teams over the past year.
The API design aims to support advanced features like bi-directional streaming, informational responses, and trailers from the start.
The client API has evolved to a “double closure” model to correctly handle concurrency and subtle cases like early server responses arriving mid-request.
Key open design questions include:
Restartable bodies: how to handle APIs that require the ability to restart a request body (for redirects and authentication) versus use cases like proxying where restart is not possible.
Client configuration: the design moved configuration from the client object to the perform method to reduce misuse that would hurt connection pooling.
API dependencies: the shape of the HTTP APIs is closely tied to the finalization of async streaming interfaces in the language itself.
HTTP API Discussion and Next Steps
There was a request for syntactic sugar for common use cases like JSON handling, to simplify the powerful but verbose streaming APIs.
This is planned but pending new Codable interfaces from the Foundation team, and a desire to avoid unnecessary Data allocations.
Jon offered to provide detailed feedback drawing on their experience building Alamofire, and asked for a summary of prior design discussions to catch up on the context.
The group agreed to use GitHub Issues in the new repository for detailed design discussions.
Volunteers stepped forward to help shepherd the HTTP API workstream, driving discussions and teeing up topics for future meetings.
WebSockets and WebTransport
There was a question about plans for client-side WebSockets and WebTransport.
The group acknowledged the importance and noted that this is currently viewed as a concrete implementation detail rather than part of the abstract HTTP API, though this is open for discussion.
Jon noted related work on an Alamofire wrapper for URLSession’s WebSocket API and the difficulties encountered due to API limitations, and offered to present on Alamofire’s API design choices in a future meeting, which was met with interest.
Next Steps & Action Items
Franz will monitor the progress of the swift-network-types repository with the core team.
Franz will follow up with the language steering group on the dependent async streaming interfaces.
Eric and Franz will work with volunteers to document the API evolution process for the new repository.
Guoye will share a list of top open HTTP API design issues to spur discussion.
Jon and Nakul will begin shepherding the HTTP API design process, organizing discussions on GitHub and for future meetings.
Jon will prepare a potential presentation on Alamofire’s API design for a future meeting.
Francesco will continue his work on a Swift client for WebTransport and share updates with the group.
I'd like to volunteer for the API evolution process document. I don't anticipate there will be many controversial points in there as there is good precedent for library evolutions in Swift, but It looks like I'll be contributing to swift-network-types so hopefully we can add that "contributor" POV as well to the document.