OpenFeign: writing Java HTTP clients as annotated interfaces

The problem OpenFeign solves for Java callers

Hand-written HTTP client code in Java tends to be boilerplate: build a URL, set a method, attach headers, serialize a body, deserialize the response, map non-2xx statuses to exceptions. OpenFeign's claim is that you can express the same call as a method on an interface and let the library do the rest. The README describes it as a Java to HTTP client binder, and says its first goal was reducing the complexity of binding Denominator uniformly to HTTP APIs regardless of how ReSTful they are.

The audience is Java developers who call an HTTP API that speaks text, typically JSON or XML, and who would rather declare the surface once than repeat the plumbing at every call site. The README also positions it against writing clients by hand with Jersey or CXF, and against sitting directly on an HTTP library such as Apache HC. The distinction is that Feign does not replace the transport, it wraps it: the repository layout includes httpclient/, okhttp/, hc5/, googlehttpclient/ and java11/ modules, which is where the underlying clients live.

That framing matters for expectations. OpenFeign is not a service framework and not an API gateway. It is the binding layer between a Java interface and an HTTP endpoint, plus a set of extension points for encoding, decoding, error handling and logging.

How annotations become a templatized HTTP request

The mechanism the README describes is annotation processing into a templatized request, with arguments applied to those templates before output. The default contract defines annotations that carry that template. @RequestLine goes on a method and defines the HttpMethod and UriTemplate; expressions wrapped in curly braces are resolved from the matching @Param annotated parameters. @Headers goes on a method or a type and defines a HeaderTemplate using the same expression resolution, applied to every request when placed on the type and only to the annotated method when placed on the method. @QueryMap goes on a parameter.

There is a detail worth noticing in the @Param row: if the annotation value is missing, Feign tries to read the parameter name from bytecode, which only works if the code was compiled with the -parameters flag. That is a real build-time dependency hiding inside an annotation table, and it is the kind of thing that produces confusing runtime failures when a build changes.

At the call site the builder assembles the pieces. The README's canonical example builds a GitHub client with Feign.builder(), a GsonDecoder, and target(GitHub.class, "https://api.github.com"). The decoder is not optional in spirit: the interface returns List<Contributor>, so something has to turn the response body into Contributor objects. Swapping GsonDecoder for another decoder module in the repository, such as jackson/, moshi/ or fastjson2/, is the intended way to change serialization. The contract, the encoder and the decoder are the three moving parts, and only the contract has a default that most users keep.

Adding feign-core from Maven Central and making a first call

The README states the library is available from Maven Central and gives the coordinates io.github.openfeign:feign-core. The version placeholder in the README is ??feign.version??, which is a documentation template rather than a real version; the recent releases listed for the project are 13.15, 13.14 and 13.13, with 13.15 published on 2026-09-09. Paste the current release in place of the placeholder.

<dependency>
    <groupId>io.github.openfeign</groupId>
    <artifactId>feign-core</artifactId>
    <version>13.15</version>
</dependency>

With that on the classpath, the smallest useful program is an interface plus a builder. The README's example adapts the canonical Retrofit sample and targets the public GitHub API. The interface declares a GET with two template expressions, and a plain class holds the response fields.

interface GitHub {
  @RequestLine("GET /repos/{owner}/{repo}/contributors")
  List<Contributor> contributors(@Param("owner") String owner, @Param("repo") String repo);
}

The builder call wires the decoder and the base URL, and the returned object is a proxy that implements the interface. What you should see when you run it is one line per contributor, printed as login followed by the contribution count, because the example loops over the returned list and prints contributor.login and contributor.contributions. Note that the GsonDecoder in that example comes from the gson/ module, not from feign-core, so a project using it needs that dependency as well. The README does not spell out that second dependency in the usage section, which is a small gap for anyone copying the snippet verbatim.

Where the text-only restriction bites

The README is explicit that Feign is limited to supporting text-based APIs. That single sentence rules out a category of work: file uploads and downloads, streaming media, protocol buffers on the wire, and anything where the body is not something a text decoder can read. If your service returns a binary attachment, OpenFeign is the wrong layer, and no amount of custom Encoder or Decoder writing changes the framing, because the decoders in the repository are built around text formats such as JSON, XML and GraphQL.

A second limitation is visible in the roadmap rather than the usage docs. The Retry API is scheduled for refactoring to support user-supplied conditions and better control over back-off policies, and the README warns in bold that this may result in non-backward-compatible breaking changes. The Logger API is also marked for refactoring toward an SLF4J-like model. Anyone building retry semantics on the current API should treat that code as likely to need rework on a future major version.

The roadmap also lists response caching, complete URI template expression support up to RFC 6570 level 4, async execution via CompletableFuture, and reactive execution via Reactive Streams as work that is not done. The README states that async and reactive support will require non-backward-compatible breaking changes. These are stated intentions, not shipped features, and the documentation does not give a timeline for any of them.

OpenFeign against Retrofit and against a plain HTTP library

The README names Retrofit as an inspiration and adapts a Retrofit sample, so the comparison is fair to draw. Both bind an interface to HTTP. The difference the README implies is in the annotation model: OpenFeign's default contract uses its own @RequestLine, @Param, @Headers and @QueryMap, while Retrofit's model is built around its own set of method and parameter annotations and a converter abstraction. OpenFeign also ships JAX-RS contracts, visible in the jaxrs/, jaxrs2/, jaxrs3/ and jaxrs4/ modules, so an interface already written against JAX-RS annotations can be reused with a different contract rather than rewritten. Retrofit does not offer that path.

The other alternative is not using a binder at all and calling Apache HC, OkHttp or the Java 11 HTTP client directly. That gives you full control over the request and response, including binary bodies, and it removes a layer from the stack trace. What you give up is the thing OpenFeign is for: the README argues it connects your code to HTTP APIs with minimal overhead and code, and that it makes replaying requests and unit testing your conversions easier. If your client surface is two endpoints, the binder is probably not worth the dependency. If it is forty endpoints across three services, the interface-per-service shape pays for itself.

Release cadence, licence and the cost of upgrading

The last push to the repository was on 2026-09-21, and the most recent release listed is 13.15 on 2026-09-09, with 13.14 on 2026-08-19 and 13.13 on 2026-06-13. That is a steady stream of minor releases rather than long-lived major versions, which has a practical consequence: pinning a version and upgrading deliberately is cheaper than floating, because the roadmap already flags breaking changes coming to Retry and to async execution. The repository also carries a feign-bom/ module, which is the conventional way to keep the core artifact and the extension modules such as gson/, jackson/ and okhttp/ on one version instead of resolving them independently.

The project is licensed under Apache-2.0, and the repository includes both a LICENSE and a NOTICE file. Apache-2.0 is a permissive licence that permits commercial use and modification, and the NOTICE file is the mechanism the licence uses for attribution when a project is redistributed. Whether your own distribution obligations are triggered depends on how you ship the dependency, which is a question for your legal team rather than something this article can settle. What can be said from the repository is that the licence and notice files are present at the top level.

Maintenance cost is mostly the version drift described above. Feign 10.x and above are built on Java 8 and should work on Java 9, 10 and 11 according to the README, and JDK 6 users are told to stay on Feign 9.x. The README does not document rollback behaviour for a failed release, so a team that needs a documented downgrade path will not find one there.

Editorial conclusion

Adopt OpenFeign when you have a text-based HTTP API and want the call site to look like a Java method call rather than a request builder, and when you are prepared to own the Contract, Encoder and Decoder choices yourself. Do not adopt it for binary payloads, since the README states Feign is limited to text-based APIs, and do not expect the Retry and Logger APIs to stay as they are, because the roadmap marks both for refactoring and says the Retry change may break backward compatibility. Before you commit, check the version of io.github.openfeign:feign-core you resolve against the 13.15 release from 2026-09-09, and check whether your build compiles with the -parameters flag, because the README says @Param without a value falls back to bytecode parameter names only when that flag is present.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. OpenFeign/feign on GitHub
4. README
5. Releases