// Module included in the following:
//
// assembly-proxy-overview.adoc

[id='con-api-compatibility{context}']
= Compatibility

There are effectively two APIs a filter developer needs to care about:

. The Filter API against which the filter is written.
This is a contract between the Filter developer and the Kroxylicious runtime. It includes `Filter`, `FilterFactory`, which the developer is responsible for implementing, and `FilterContext` and `FilterFactoryContext`, which are provided by the Kroxylicous runtime for the developer to use.
. The "configuration API" that your filter exposes. This is a contract between the Filter developer and Kroxylicious users.

== Compatibility of the Filter API

The Kroxylicious project uses semantic versioning.
For the filter API this means that you can compile your filter against the Kroxylicious API at version _x.y~c~.z~c~_ and users will be able to use it with Kroxylicious runtimes at version _x.y~r~.z~r~_ if the runtime version is not older than the compile time version (that is if _y~r~_ ≥ _y~c~_ and _z~r~_ ≥ _z~c~_).

== Compatibility of your Filter configuration

The Kroxylicious proxy isn't able to provide or enforce any compatibility guarantees about the configuration API that your plugin offers to users.
In other words you are free you release your plugin at version _a.b.c_ and later release a version _a.d.e_ which doesn't accept the same configuration syntax (JSON or YAML) that the original version did.

Doing this makes it more difficult for users to upgrade from older versions on your plugin, because they will have to rewrite and revalidate the configuration which worked with the old version.

For this reason filter developers are strongly encouraged to adopt Semantic versioning as the way to communicate compatibility of the configuration API they offer to users.
