Simple fluent style Java API to make API calls.
- Because you want everything explicit, everything deterministic, request/response coupled (as it should be).
- Because you want no hidden behavior, hidden headers, hidden parameters, etc.
- Because you want to change the underlying HTTP client by changing one line in your client and one dependency.
- Because you want to be able to use a fluent style API to make API calls in a very easy way.
- Because you want to be able to mock up API calls without using external HTTP libraries.
Currently, it wraps over the java.net.http library but you can easily extend it to use other HTTP clients/libraries
by implementing the HttpExchangeClient interface or by extending the AbstractHttpExchangeClient.
- Support for Apache HttpClient5 is already available in the
apiphany-httpclient5module and can be used by adding the dependency and changing one line in your client constructor. - Support for OkHttp is already available in the
apiphany-okhttpmodule and can be used by adding the dependency and changing one line in your client constructor. - Support for RestTemplate and RestClient is already available in the
apiphany-springmodule and can be used by adding the dependency and changing one line in your client constructor.
Support is being developed for other HTTP clients like Netty, Jersey, etc. If you want to contribute with an implementation for a new HTTP client, please check the contribution guidelines and feel free to open a PR.
Current release 1.3.1
Maven: add this dependency to your pom.xml
<dependency>
<groupId>io.github.raduking</groupId>
<artifactId>apiphany</artifactId>
<version>1.3.1</version>
</dependency>You can also use the latest development build, but you need to build it yourself.
git clone git@github.com:raduking/apiphany.git
cd apiphany
git checkout develop
mvn clean install
The project being in active development. Expect class name changes, method name changes, and other similar changes between versions. All such changes are documented in CHANGELOG.md.
WARNING: Every new version should be treated as Major and having breaking changes.
To make a simple HTTP GET request to http://my.awesome.domain/api/info:
import org.apiphany.ApiClient;
public class MyAwesomeClient extends ApiClient {
public MyAwesomeClient() {
super("http://my.awesome.domain");
}
public String getInfo() {
return client()
.http()
.get()
.path("api", "info")
.retrieve(String.class)
.orNull();
}
}void main() {
MyAwesomeClient client = new MyAwesomeClient();
String info = client.getInfo();
System.out.println("Info: " + info);
}If you think in curl, here is the equivalent Apiphany fluent call.
curl -X POST "https://api.example.com/v1/users" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"John"}'Apiphany:
import static org.apiphany.Api.http;
String result = http()
.post()
.url("https://api.example.com/v1/users")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\"name\":\"John\"}")
.retrieve(String.class)
.orRethrow();By default Apiphany uses the JDK java.net.http client. You can switch to another implementation by adding the corresponding module dependency and passing an exchange client instance to http(...). No other code changes are needed.
Add the apiphany-httpclient5 dependency, then:
import org.apiphany.client.http.ApacheHC5HttpExchangeClient;
ExchangeClient client = new ApacheHC5HttpExchangeClient();
String name = http(client)
.get()
.url("https://api.example.com/v1/users/1")
.retrieve(String.class)
.orRethrow();Add the apiphany-okhttp dependency, then:
import org.apiphany.client.http.OkHttpExchangeClient;
ExchangeClient client = new OkHttpExchangeClient();
String name = http(client)
.get()
.url("https://api.example.com/v1/users/1")
.retrieve(String.class)
.orRethrow();Add the apiphany-spring dependency, then:
import org.apiphany.client.http.SpringRestExchangeClient;
ExchangeClient client = new SpringRestExchangeClient();
String name = http(client)
.get()
.url("https://api.example.com/v1/users/1")
.retrieve(String.class)
.orRethrow();See the docs directory for project specifications, architecture notes, and user guides.