Skip to content
radukingPublic

About

API Requests

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

Apiphany

Simple fluent style Java API to make API calls.

Maven Central GitHub Release Release Date
Java License Javadoc PRs

Status

branch: master Build (master) branch: develop Build (develop)

Languages and Tools

java maven junit git github actions

Why Apiphany?

  • 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.

Client Support

  • Support for Apache HttpClient5 is already available in the apiphany-httpclient5 module 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-okhttp module 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-spring module 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.

License

Apache License, Version 2.0

Releases

Current release 1.3.1

Getting Started

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.

How to use

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);
}

CURL-like usage

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();

Choosing the HTTP client

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.

Apache HttpClient5

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();

OkHttp

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();

Spring RestClient

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();

Documentation

See the docs directory for project specifications, architecture notes, and user guides.

About

API Requests

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages