OpenFeign — Declarative REST Client for Java Microservices

Introduction

OpenFeign simplifies writing HTTP API clients in Java by letting developers declare REST endpoints as interface methods with annotations. The framework generates the implementation at runtime, handling URL construction, parameter encoding, request/response serialization, and error handling. It originated at Netflix as part of their microservices stack and is widely used in Spring Cloud applications.

What OpenFeign Does

• Generates HTTP client implementations from annotated Java interfaces at runtime
• Supports pluggable encoders and decoders (Gson, Jackson, JAXB, SAX)
• Provides built-in retry logic, error handling, and request interceptors
• Integrates with service discovery systems (Eureka, Consul) via Spring Cloud OpenFeign
• Supports synchronous and reactive HTTP calls with pluggable HTTP backends

Architecture Overview

Feign uses a reflective proxy to intercept method calls on annotated interfaces. Each call is routed through a chain: the Contract parses annotations into request metadata, the Encoder serializes the body, the Client (OkHttp, Apache HC, or Java 11 HttpClient) executes the request, and the Decoder deserializes the response. Interceptors can modify requests (add headers, auth tokens) before they are sent. The entire pipeline is composable and replaceable.

Self-Hosting & Configuration

• Add feign-core and a decoder module (feign-gson, feign-jackson) to your build
• Use Spring Cloud OpenFeign (@EnableFeignClients) for automatic service discovery integration
• Configure timeouts, retries, and connection pools via Feign.Builder options
• Add request interceptors for authentication headers (OAuth2, API keys)
• Enable logging with feign-slf4j for request/response debugging

Key Features

• Declarative API — define REST clients as interfaces with zero boilerplate
• Pluggable HTTP backends: OkHttp, Apache HttpClient, Java 11+ HttpClient
• Built-in error decoder for mapping HTTP error responses to Java exceptions
• Contract system supports JAX-RS, Spring MVC, and custom annotation styles
• Query map support for dynamic query parameters from POJOs or maps

Comparison with Similar Tools

• RestTemplate — Spring's older imperative HTTP client; OpenFeign is more concise and declarative
• WebClient — Spring's reactive HTTP client; OpenFeign is simpler for synchronous microservice calls
• Retrofit — similar declarative approach for Android/Java; OpenFeign is more common in Spring Cloud ecosystems
• OkHttp — lower-level HTTP client; OpenFeign builds on top of clients like OkHttp to add declarative interfaces

FAQ

Q: Should I use OpenFeign or WebClient in Spring Boot? A: Use OpenFeign for straightforward synchronous REST calls. Use WebClient for reactive or streaming use cases.

Q: Does OpenFeign support async/reactive calls? A: Yes. Feign supports CompletableFuture return types and integrates with reactive HTTP backends.

Q: Can I use OpenFeign without Spring? A: Yes. Feign-core is a standalone library. Spring Cloud OpenFeign adds auto-configuration and service discovery on top.

Q: How do I handle errors from downstream services? A: Implement a custom ErrorDecoder to map HTTP error codes to domain-specific exceptions.

Sources

• https://github.com/OpenFeign/feign
• https://docs.spring.io/spring-cloud-openfeign/