Jersey: the JAX-RS reference implementation with extensions of its own

A reference implementation, not a client library

Jersey is a REST framework that provides a JAX-RS reference implementation and more. That distinction sets the scale of the project before any code is written. A reference implementation is the one the specification is written against and the one that ships inside a server, so Jersey's job is to be correct and complete against the API, not small.

On top of the specification, Jersey provides its own APIs that extend the JAX-RS toolkit with additional features and utilities for service and client development, and it exposes numerous extension SPIs so developers can extend Jersey itself. Two extension directions in one project: extending the specification for your application, and extending the framework for everybody else.

The stated goals make the intent clear. Jersey tracks the JAX-RS API and provides regular releases of production quality reference implementations that ship with GlassFish, it provides APIs to extend Jersey and aims to build a community of users and developers, and it aims to make it easy to build RESTful web services using Java and the Java Virtual Machine.

The shipping-with-GlassFish point matters for anyone choosing a stack. Jersey is not a library you bolt onto an arbitrary server and hope for the best; it is the implementation the reference distribution carries, which means the version alignment questions are already answered for you if you use that server.

The module layout shows how much surface there is

The top-level directory listing is a better description of Jersey than the readme is.

The core is split into three modules: core-common for what both sides share, core-server for the server side and core-client for the client side. Around them sit the parts that extend the framework rather than implement the specification. inject/ is the dependency injection support, media/ handles message body readers and writers, security/ holds the security providers, connectors/ holds the HTTP connectors, and containers/ holds the integration with servlet containers and similar runtimes.

Then there is the tooling and the support surface. tools/ holds tooling modules, bom/ holds the dependency list used for managing versions, bundles/ holds OSGi bundles, archetypes/ holds Maven archetypes for generating new projects, incubator/ holds experimental modules, test-framework/ is the Jersey test framework, and tests/ and docs/ are the test suite and documentation sources.

ext/ is the extension directory, and this is where the most interesting part of the project sits for anyone who has outgrown the standard API. The examples directory shows what those extensions look like in practice, with bookmark, bookmark-em, bookstore-webapp, cdi-webapp, clipboard, configured-client, declarative-linking, entity-filtering, entity-filtering-security, entity-filtering-selectable, exception-mapping, extended-wadl-webapp, freemarker-webapp, groovy, helloworld-cdi2-se, helloworld-helidon, helloworld-netty, and more.

Two things stand out in that list. The entity-filtering examples, in three variants covering the basic case, the selectable case and the security case, show a capability that goes well beyond what the specification requires. The helloworld examples come in a Netty flavour, a Helidon flavour and a CDI 2 SE flavour, which tells you the framework is not tied to a single server or to a single injection model.

Where to get it and where to ask

The repository does not document an installation command, and that is not an omission so much as a division of labour. The documentation lives on the Jersey website, hosted as the Eclipse project page, and the readme sends you there for the content that would normally sit in a readme.

What the repository does carry is the licensing and governance information, which for a foundation project is the part worth reading before anything else.

Jersey is licensed under a dual licence, EPL 2.0 and GPL 2.0 with Classpath Exception, and you can choose whichever of the two suits your needs better and use it under those terms. The header comment in the source files states it as EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0, and the licence text is in LICENSE.md with a NOTICE.md alongside it.

Contributions are a separate matter from use. The project uses a contribution policy, which means contributions can only be accepted under the terms of the Eclipse Contributor Agreement. In practice that means an external contributor signs an ECA rather than signing a dual licence choice, and an organisation that has a policy about inbound patent grants and outbound copyright assignment needs to know that before a patch lands.

For help, the project points to the mailing list at [email protected], which requires subscribing first, to the StackOverflow tag for Jersey, and to the GitHub issue tracker. The API documentation is published as Javadoc at the jersey-api reference, and there is a Twitter account for release notes.

Three release lines are being published at once

The version history is the most useful signal here, because Jersey is old enough to have accumulated parallel lines rather than a single moving branch.

The three most recent releases are 4.0.3 published on 2026-10-01, 3.1.12 published on 2026-06-11, and 2.48 published on 2026-03-18. The default branch is 4.x, so the newest line is where new development lands, but the older two lines still received releases in 2026, which means the project is maintaining three streams of a mature framework at once.

That is a commitment with a cost. A framework with three supported lines needs its security and dependency updates applied three times, and it means the maintenance burden does not shrink when you release. The benefit is that an organisation which upgraded to 3.x two years ago is not forced to jump to 4.x just to receive a fix, which for a library that sits under every service in a stack is the difference between a scheduled upgrade and an emergency one.

The repository is not archived and the last push was on 2026-10-20, three weeks after the 4.0.3 tag, so work continues on the 4.x branch between releases.

The build configuration also suggests a mixed toolchain history. There is a pom.xml at the root for Maven, a .travis.yml for the older continuous integration setup, and a .github/ directory for the current one. The presence of both is a reminder that a project this age accumulates infrastructure rather than replacing it.

What Jersey is the wrong choice for

The case against Jersey is mostly about size and about what the framework expects from its environment.

First, the module count. core-common, core-server, core-client, inject, media, security, connectors, containers, ext, tools, bom, bundles, archetypes, test-framework, incubator. This is not a library you add for one call. A team that needs to send an HTTP request to a JSON API is served better by a small client, and the documentation for the client side is a different product from the server framework even though it lives in the same repository.

Second, the server orientation. Most of the value in Jersey is in the server side: the resource model, the message body providers, the entity filtering, the WADL support, the security providers. Those need a runtime, whether that is a servlet container, the Netty connector, or a CDI environment such as Helidon. A pure command line program that wants to publish a REST endpoint has more to configure than it wants.

Third, the specification itself. Choosing JAX-RS means accepting the API shape, with its annotations, its resource model and its provider contracts, and inheriting its constraints. If the goal is something like GraphQL, gRPC with a Java stub layer, or a hand rolled HTTP server with full control over the wire, then the specification is a restriction rather than a shortcut, and no amount of extension will change that.

The extension SPIs soften the second and third points without removing them. They are the reason a long lived project survives, and the reason the incubator directory exists, but they work within the specification's shape rather than around it.

Editorial conclusion

Jersey suits a Java team that has standardised on JAX-RS and wants the reference implementation rather than a lighter client, especially where WADL, entity filtering, security or CDI integration matter. It does not suit a team looking for a small HTTP client library, since the module layout is large and the framework expects a servlet or container environment for most of its value. Before adopting it, pick the release line you will live on from the three the project publishes, since the default branch is 4.x while 3.1.12 and 2.48 are still tagged, and confirm the Classpath Exception variant of the GPL is the one your organisation can accept.

Frequently asked questions

Official sources

1. eclipse-ee4j/jersey on GitHub
2. Issues
3. Project website
4. README
5. Releases