Compatibility Guidelines

Binary Compatibility Rules

Apache Pekko HTTP follows the same binary compatibility rules as Apache Pekko itself. In short it means that the versioning scheme should be read as major.minor.patch, wherein all versions with the same major version are backwards binary-compatible, with the exception of @ApiMayChange, @InternalApi or @DoNotInherit marked APIs or other specifically documented special-cases.

For more information and a detailed discussion of these rules and guarantees please refer to The @DoNotInherit and @ApiMayChange markers.

Components with no Binary Compatibility Guarantee

The following components and modules don’t have the previously mentioned binary compatibility guaranteed within minor or patch versions. However, binary compatibility will be attempted to be kept as much as possible.

pekko-http

Scala

org.apache.pekko.http.scaladsl.server.directives.FileUploadDirectives#storeUploadedFile
org.apache.pekko.http.scaladsl.server.directives.FileUploadDirectives#storeUploadedFiles
org.apache.pekko.http.scaladsl.server.directives.FileUploadDirectives#fileUploadAll
org.apache.pekko.http.scaladsl.marshalling.sse.EventStreamMarshalling
org.apache.pekko.http.scaladsl.server.HttpApp
org.apache.pekko.http.scaladsl.unmarshalling.sse.EventStreamParser
org.apache.pekko.http.scaladsl.unmarshalling.sse.EventStreamUnmarshalling
org.apache.pekko.http.scaladsl.OutgoingConnectionBuilder#managedPersistentHttp2
org.apache.pekko.http.scaladsl.OutgoingConnectionBuilder#managedPersistentHttp2WithPriorKnowledge

Java

org.apache.pekko.http.javadsl.common.PartialApplication#bindParameter
org.apache.pekko.http.javadsl.server.Directives#anyOf (all overloads)
org.apache.pekko.http.javadsl.server.Directives#allOf (all overloads)
org.apache.pekko.http.javadsl.server.directives.FileUploadDirectives#storeUploadedFile
org.apache.pekko.http.javadsl.server.directives.FileUploadDirectives#storeUploadedFiles
org.apache.pekko.http.javadsl.server.directives.FileUploadDirectives#fileUploadAll
org.apache.pekko.http.javadsl.server.HttpApp
org.apache.pekko.http.javadsl.model.RequestResponseAssociation
org.apache.pekko.http.javadsl.OutgoingConnectionBuilder#managedPersistentHttp2WithPriorKnowledge
org.apache.pekko.http.javadsl.OutgoingConnectionBuilder#managedPersistentHttp2

pekko-http-caching

Scala

org.apache.pekko.http.caching.LfuCache
org.apache.pekko.http.caching.scaladsl.Cache
org.apache.pekko.http.scaladsl.server.directives.CachingDirectives

Java

org.apache.pekko.http.caching.LfuCache
org.apache.pekko.http.caching.javadsl.Cache
org.apache.pekko.http.javadsl.server.directives.CachingDirectives

pekko-http-core

Scala

org.apache.pekko.http.scaladsl.ClientTransport
org.apache.pekko.http.scaladsl.ConnectionContext#httpsClient
org.apache.pekko.http.scaladsl.ConnectionContext#httpsServer
org.apache.pekko.http.scaladsl.settings.PoolImplementation
org.apache.pekko.http.scaladsl.settings.ClientConnectionSettings#transport
org.apache.pekko.http.scaladsl.settings.ClientConnectionSettings#withTransport
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#appendHostOverride
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#poolImplementation
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#responseEntitySubscriptionTimeout
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#withHostOverrides
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#withOverrides
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#withPoolImplementation
org.apache.pekko.http.scaladsl.settings.ConnectionPoolSettings#withResponseEntitySubscriptionTimeout
org.apache.pekko.http.scaladsl.settings.HostOverride
org.apache.pekko.http.scaladsl.settings.Http2ServerSettings
org.apache.pekko.http.scaladsl.settings.Http2ClientSettings
org.apache.pekko.http.scaladsl.settings.PreviewServerSettings
org.apache.pekko.http.scaladsl.settings.ServerSentEventSettings
org.apache.pekko.http.scaladsl.model.headers.CacheDirectives.immutableDirective
org.apache.pekko.http.scaladsl.model.headers.X-Forwarded-Host
org.apache.pekko.http.scaladsl.model.headers.X-Forwarded-Proto
org.apache.pekko.http.scaladsl.model.http2.PeerClosedStreamException
org.apache.pekko.http.scaladsl.model.http2.Http2Exception
org.apache.pekko.http.scaladsl.model.SimpleRequestResponseAttribute
org.apache.pekko.http.scaladsl.model.RequestResponseAssociation

Java

org.apache.pekko.http.javadsl.ClientTransport
org.apache.pekko.http.javadsl.ConnectionContext#httpsClient
org.apache.pekko.http.javadsl.ConnectionContext#httpsServer
org.apache.pekko.http.javadsl.settings.ClientConnectionSettings#getTransport
org.apache.pekko.http.javadsl.settings.ClientConnectionSettings#withTransport
org.apache.pekko.http.javadsl.settings.ConnectionPoolSettings#appendHostOverride
org.apache.pekko.http.javadsl.settings.ConnectionPoolSettings#getPoolImplementation
org.apache.pekko.http.javadsl.settings.ConnectionPoolSettings#getResponseEntitySubscriptionTimeout
org.apache.pekko.http.javadsl.settings.ConnectionPoolSettings#withHostOverrides
org.apache.pekko.http.javadsl.settings.ConnectionPoolSettings#withPoolImplementation
org.apache.pekko.http.javadsl.settings.ConnectionPoolSettings#withResponseEntitySubscriptionTimeout
org.apache.pekko.http.javadsl.settings.PoolImplementation
org.apache.pekko.http.javadsl.settings.PreviewServerSettings
org.apache.pekko.http.javadsl.settings.ServerSentEventSettings

Versioning and Compatibility

The Apache Pekko HTTP Team currently does not intend to break binary compatibility, i.e. no binary incompatible 2.x.y release is currently planned.

Specific versions inter-op discussion

In this section we discuss some of the specific cases of compatibility between versions of Apache Pekko HTTP and Apache Pekko itself.

For example, you may be interested in those examples if you encountered the following exception in your system when upgrading parts of your libraries: Detected java.lang.NoSuchMethodError error, which MAY be caused by incompatible Pekko versions on the classpath. Please note that a given Pekko version MUST be the same across all modules of Apache Pekko that you are using, e.g. if you use pekko-actor [2.5.3 (resolved from current classpath)] all other core Apache Pekko modules MUST be of the same version. External projects like Apache Pekko Connectors, Persistence plugins or Apache Pekko HTTP etc. have their own version numbers - please make sure you're using a compatible set of libraries.

Compatibility with Apache Pekko

To facilitate supporting multiple minor versions of Apache Pekko we do not depend on pekko-stream explicitly but mark it as a provided dependency in our build. That means that you will always have to add a manual dependency to pekko-stream.

The same goes for pekko-http-testkit: If the testkit is used, explicitly declare the dependency on pekko-stream-testkit of same Pekko version as pekko-stream.

sbt

val PekkoVersion = "1.0.2"
val PekkoHttpVersion = "1.0.1"
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-http" % PekkoHttpVersion,
  "org.apache.pekko" %% "pekko-stream" % PekkoVersion,
  "org.apache.pekko" %% "pekko-http-testkit" % PekkoHttpVersion % "Test",
  "org.apache.pekko" %% "pekko-stream-testkit" % PekkoVersion % "Test"
)

Gradle

def versions = [
  PekkoVersion: "1.0.2",
  ScalaBinary: "2.13"
]
dependencies {
  implementation platform("org.apache.pekko:pekko-http-bom_${versions.ScalaBinary}:1.0.1")

  implementation "org.apache.pekko:pekko-http_${versions.ScalaBinary}"
  implementation "org.apache.pekko:pekko-stream_${versions.ScalaBinary}:${versions.PekkoVersion}"
  Test "org.apache.pekko:pekko-http-testkit_${versions.ScalaBinary}"
  Test "org.apache.pekko:pekko-stream-testkit_${versions.ScalaBinary}:${versions.PekkoVersion}"
}

Maven

<properties>
  <pekko.version>1.0.2</pekko.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.pekko</groupId>
      <artifactId>pekko-http-bom_${scala.binary.version}</artifactId>
      <version>1.0.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-http_${scala.binary.version}</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-stream_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-http-testkit_${scala.binary.version}</artifactId>
    <scope>Test</scope>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-stream-testkit_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
    <scope>Test</scope>
  </dependency>
</dependencies>

Edit this page

1.0.1