grpc-swift/Sources/GRPCCore/Documentation.docc/Articles/Public-API.md

Public API

Understand what constitutes the public API of gRPC Swift and the commitments made by the maintainers.

Overview

The gRPC Swift project uses Semantic Versioning 2.0.0 which requires projects to declare their public API. This document describes what is and isn't part of the public API; commitments the maintainers make relating to the API, and guidelines for users.

For clarity, the project is comprised of the following Swift packages:

• grpc/grpc-swift,
• grpc/grpc-swift-nio-transport,
• grpc/grpc-swift-protobuf, and
• grpc/grpc-swift-extras.

What is and isn't public API

Library targets

All library targets made available as package products are considered to be public API. Examples of these include GRPCCore and GRPCProtobuf.

Exceptions: Targets with names starting with an underscore (_) aren't public API.

Symbols

All publicly exposed symbols (i.e. symbols which are declared as public) within public library targets or those which are re-exported from non-public targets are part of the public API. Examples include Metadata, ServiceConfig, and GRPCServer.

Exceptions:

• Symbols starting with an underscore (_), for example _someFunction() and _AnotherType aren't public API.
• Initializers where the first character of the first parameter label is an underscore, for example init(_foo:) aren't public API.

Configuration and inputs

Any configuration, input, and interfaces to executable products which have inputs (such as command line arguments, or configuration files) are considered to be public API. Examples of these include the configuration file passed to the Swift Package Manager build plugin for generating stubs provided by grpc-swift-protobuf.

Exceptions:

• Executable targets which aren't exposed as executable products.

Commitments made by the maintainers

Without releasing a new major version, the gRPC Swift maintainers commit to not adding any new types to the global namespace without a "GRPC" prefix.

To illustrate this, the maintainers may:

1. Add a new type to an existing module called GRPCPanCakes but will not add a new type called PanCakes to an existing module.
2. Add a new top-level function to an existing module called grpcRun() but won't add a new top-level function called run().
3. Add a new module called GRPCFoo. Any symbols added to the new module at the point the module becomes API aren't required to have a "GRPC" prefix; symbols added after that point will be prefixed as required by (1) and (2).

This allows the project to follow Semantic versioning without breaking adopter code in minor and patch releases.

Guidelines for users

In order to not have your code broken by a gRPC Swift update you should only use the public API as described above. There are a number of other guidelines you should follow as well:

1. You may conform your own types to protocols provided by gRPC Swift.
2. You may conform types provided by gRPC Swift to your own protocols.
3. You mustn't conform types provided by gRPC Swift to protocols that you don't own, and you mustn't conform types you don't own to protocols provided by gRPC Swift.
4. You may extend types provided by gRPC Swift at package, internal, private or fileprivate level.
5. You may extend types provided by gRPC Swift at public access level if doing so means that a symbol clash is impossible (such as including a type you own in the signature, or prefixing the method with the namespace of your package in much the same way that gRPC Swift will prefix new symbols).