Deep dive: HTTP APIs: Alamofire design decisions (20 min)
HTTP APIs: Open design questions (15 min)
Shepherded by Jon and Nakul
Restartable bodies
Client configuration
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 group covered progress on the new swift-networking-types repository and the contribution and evolution process the workgroup is drafting to go with it. The deep dive was a presentation on Alamofire’s history and design, which teed up the main discussion of the meeting: the appropriate API layering for a new Swift HTTP client, with the group weighing a single progressively-disclosed API against separate high-level and low-level clients. The group agreed that API layering is a top-level open question for the HTTP client design and will continue the discussion in the forums.
Notes
Swift Networking Types Repository Update
The repository name swift-networking-types is confirmed and its creation is in progress.
The group agreed on a contribution strategy: start with rapid pull requests for small, consensus-based changes to build momentum.
There was discussion of a process for introducing new APIs: develop new features behind experimental flags, and once an API is considered stable, take it through a full Swift Evolution-style review in the forums starting with a pitch.
A process document, closely mirroring the standard Swift Evolution process, is being drafted to formalize the workgroup’s procedures.
Alamofire Deep Dive (presentation by Jon)
Jon presented the history and architecture of Alamofire, a widely-used Swift networking library built on top of URLSession.
Key design points included its use of the delegate pattern for customization, its own state management on top of URLSessionTask, and its evolution toward modern concurrency with DispatchQueue and async/await.
Jon noted a 10-20% performance overhead compared to raw URLSession, attributing it to additional state management and identifying specific bottlenecks like the Progress object.
The WebSocket implementation was highlighted as an example of simplifying a complex native API (URLSessionWebSocketTask) by adding features like generic decoding, automatic ping handling, and a recursive listener loop to expose messages as a stream.
HTTP Client API Layering
The central discussion was on the appropriate API layering for the new HTTP client.
One view favored a single, progressively-disclosed API where users could “pierce the veil” to access lower-level functionality from a high-level request object when needed.
Another view favored two distinct clients: a high-level client with built-in features like redirects and cookie handling for most use cases, and a separate, explicit low-level client for server-side development or scenarios requiring fine-grained control. The concern was that a single API could be confusing and that most client-side developers should be shielded from low-level semantics.
Insights were shared from building URLSession: while features like redirects, authentication, and caching are modular, their composition order is often fixed, suggesting that a fully flexible “pluggable middleware” approach has practical limitations.
The group agreed that any API design must be forward-looking, allowing for the adoption of new HTTP protocol features (for example, early data in HTTP/3) without breaking API contracts.
The group agreed to continue the discussion in the forums as a top-level open question for the HTTP client design.
Related Technical Discussions
The group discussed the design of URLSessionWebSocketTask’s receive method, which provides backpressure by requiring an explicit call for each message.
A caution was raised against tightly coupling the new networking APIs with the current Codableimplementation, as Codable is expected to be redesigned. The group noted the need to influence that redesign so it better supports streaming data.
Next Steps & Action Items
Eric will circulate a draft document for the proposed contribution and review process. This will eventually help form the basis of the contributing.md file for the new swift-networking-types repository.
Tommy will coordinate landing the uncontroversial parts of the currency types proposals in the new repository.
Jon and Nakul will continue shepherding the HTTP API design process and tracking open questions in the forums.
The group will continue the API layering discussion in the forums as a top-level open question for the HTTP client design.
The group will ensure that as new versions of Codable are designed, the needs of streaming data decoding are considered.
(I apologize on behalf of my Monday morning brain.)