Server APIs Project

Server APIs Project

Article source：https://swift.org/server-apis/

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:

• They will provide access to low-level, standards defined capabilities such as sockets, HTTP parsing and security.

• They will be cross-platform and work on platforms supported by Swift.

• They will not provide high level server frameworks such as web frameworks. Instead, they serve as a foundation to enable those frameworks to be developed by others.

• The design of the APIs will involve representatives from developers of server-side frameworks and applications. These representatives from the community will both provide input to the API design and implementation, and act as early adopters for the APIs.

• The APIs are intended to provide maximum interoperability with other Swift APIs by using primitive data types from the Standard Library and Foundation (where appropriate).

• A starting design goal is for these libraries to be delivered as packages via the Swift Package Manager, although the precise way these libraries will be distributed will be determined once the effort is farther along.

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:

• Base Networking: Provide a portable interface for low level socket-based network I/O, including TCP/IP and UDP protocols, IPv4 and IPv6 support and domain name resolution. Support should be provided to create and use both synchronous and asynchronous non-blocking connections.

• Security and Encryption: Provide common cryptographic constants and cyphers along with keychain and certificate management, and SSL/TLS based secure transport. This must integrate with the base networking support to provide secure sockets, and with the HTTP parsing library to provide HTTPS support.

• HTTP and WebSockets: Provide low level HTTP parsing, including HTTP, HTTP/2 and WebSocket support making it possible, in conjunction with the security and networking APIs, to create secure HTTP and WebSocket servers.

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):

• Chris Bailey (@seabaylea, IBM Kitura)
• Logan Wright (@LoganWright, Vapor)
• Paulo Faria (@paulofaria, Zewo)
• Steve Algernon (@salgernon, Apple)

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:

• Daniel Dunbar (@ddunbar, Apple)
• Gregor Milos (@gmilos, Apple)
• Kyle Jessup (@kjessup, Perfect)
• Robert Dickerson (@rfdickerson, IBM Kitura)
• Tanner Nelson (@tannernelson, Vapor)
• Tom Doron (@tomerd, Apple)

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 set of capabilities and function targeted for implementation
• Why those functions are useful and what types of server frameworks for applications would benefit from them
• How those functions would be used, and an initial overview of the intended approach to implement them

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.