Server APIs Project

Swift has amazing potential on the server, and to be an even better language for server-side development Swift needs great low-level APIs common among server frameworks. The Server APIs project will provide core capabilities in areas such as networking and security so Swift programs no longer need to frequently rely on platform-specific C libraries to provide this functionality. As a result, developers will be able to create frameworks and server applications using pure-Swift code, without the need to also have systems programming skills and knowledge of multiple platforms.

While very early in development, the Server APIs are intended to have the following key characteristics:

The Server APIs project is being managed as part of the Swift.org open source community. The Server APIs are in the early stages of development, and we are excited to design and build these APIs in public from the very beginning. This project is not yet tied to release along with any specific version of the Swift language, allowing this project to mature at its own pace as Swift marches on toward version 4.

Focus Areas

The project will initially focus on producing API proposals for base networking, security and encryption, and HTTP parsing:

Portability

A key goal of Server APIs is to support both the platforms that Swift is currently available on, and be in a position to adopt new platforms as and when Swift support is added. This means that there must be consistent APIs across platforms to ensure code portability. There may be alternative underlying implementations, however, on each platform. Further, in order to avoid the API providing only the lowest common denominator of capabilities across all the platforms, platform specific extensions can be added.

Using External Libraries

Where there are existing well supported libraries on a platform these should be assessed for use in conjunction with a Swift overlay, provided they meet the designed Swift API specification. While it may be desirable to implement the APIs using pure Swift code in the future, using existing libraries enables capabilities to be delivered more rapidly and allows Swift to benefit from existing communities.

APIs can subsequently evolve to have pure Swift implementations where there are advantages, including improved performance, user-experience (usage, installability), or maintenance.

Note that the use of any library for this purpose must be explicitly approved by the Project lead per the general policy of adding dependencies on external libraries to the Swift project.

Work Group

The creation of these APIs will be steered by a work group consisting of a steering team, stakeholders from the server-side Swift community, and anyone who wants to get involved. The work group consists of three roles: steering team member, stakeholder, and contributor. Participants may have more than one role in the work group.

Everyone is welcome to contribute to the Server APIs Work Group through participating in a range of activities including joining as a stakeholder, participating in design discussions, asking or answering questions on the mailing lists, reporting or triaging bugs or by submitting pull requests to the project(s) for implementation or tests.

Steering Team

Analagous to the primary Core Team for Swift, the work group has a steering team that is responsible for providing overall technical direction, ensuring co-ordination both between the various API efforts (for example around network security and HTTP integration for HTTPS) and with the wider Swift Core Libraries and language. Membership of the steering team is contribution based and is expected to evolve over time.

The initial steering team consists of the following people (and their GitHub IDs):

Additionally it is expected that sub-teams will form over time to focus on specific API areas.

Stakeholders

The work group also has stakeholders who represent server-side frameworks or applications. They are responsible for providing early input on use cases and API design as part of the iterative design and implementation process, and to adopt the new APIs into their frameworks.

Joining and leaving the work group as a stakeholder is a straightforward process. The only requirement is to raise a Pull Request to add or remove your name from the stakeholder list in the work group GitHub project, which will act to add or remove you from invites to formal work group discussions.

The initial stakeholders consists of:

Development Process

The development of new server-focused APIs under the guidance of the Server APIs work group occurs in three phases: API Proposal, Prototyping and Development, and Release.

API Proposals

Proposals for new APIs are created by the Server APIs steering team, stakeholders, and contributors. The initial API proposal is not a full API specification with a detailed architecture and design. The initial proposal should be use case focused, highlighting:

The API proposal is then reviewed and approved by the steering team and stakeholders who look to validate that the proposed functions are reasonable capabilities to be added, that they fit within the remit of the Server APIs work group, and that the overall approach is valid.

The proposal is then socialized with the wider Swift community as a “Pitch” in the Swift Evolution process.

Prototyping and Development

Once the API proposal is approved by the steering team and stakeholders, and input has been received from the wider community via Swift Evolution, prototyping and development can begin. This is an iterative process involving four steps:

  1. Develop: Development is done by the work group contributors to produce an incubator release. Function is added incrementally, adding tests and documentation as part of the development process.

  2. Release: Once sufficient new function has been developed, the steering team and stakeholders branch the code to provide a new incubator release. The availability of the release for testing, adoption and feedback is then announced using the Swift evolution-announce mailing list

  3. Adopt: The incubator release is then adopted by the stakeholders and the wider community in order to assess the APIs for usability, coverage and quality.

  4. Feedback: Finally, any feedback from the stakeholders and wider community is fed back into the next development cycle.

Once the full set of function has been developed, released, adopted and feedback acted on, the steering team and stake holders will branch a formal Preview release.

Release Process

In addition to soliciting feedback from the wider community at the initial pitch and development milestones, once a preview release is available a formal Swift Evolution proposal is published and announced via the Swift Evolution mailing list. This gives the wider community a formal opportunity to review the final API and architecture and provide feedback before the library is released.

Mailing List

The Server APIs Work Group utilizes the swift-server-dev mailing list for general discussion.