Jurl is a modern Java http client designed to make API integrations simpler.
The top StackOverflow answer to "How to make an HTTP request in Java" is terrifying:
Even Apache's HttpClient
leaves an uncharacteristic trail of boilerplate code.
String html = new Jurl()
.url("https://www.google.com/")
.param("hl", "es") // spanish!
.go()
.getResponseBody();
Jurl uses Jackson to parse json responses.
@JsonIgnoreProperties(ignoreUnknown = true)
public static class SpotifyArtist {
public String name;
public String href;
public List<String> genres;
}
SpotifyArtist artist = new Jurl()
.url("https://api.spotify.com/v1/artists/147jymD5t0TCXW0DbaXry0")
.go()
.getResponseJsonObject(SpotifyArtist.class);
It may be expedient to parse JSON responses into Map<String, Object>
.
Map<String, Object> geocodeResults = new Jurl()
.url("https://maps.googleapis.com/maps/api/geocode/json")
.param("address", "131 West Wilson Street, Madison WI")
.go()
.getResponseJsonMap();
If throwOnNon200(true)
is set, go()
will throw JurlHttpStatusCodeException
on non-200
response codes.
try {
SpotifyArtist artist2 = new Jurl()
.url("https://api.spotify.com/v1/artists/not-an-artist")
.throwOnNon200(true)
.go()
.getResponseJsonObject(SpotifyArtist.class);
} catch (JurlHttpStatusCodeException e) {
Jurl jurlInstance = e.getJurlInstance();
// ...
}
Otherwise, you can always check the response code using getResponseCode()
.
Jurl jurl = new Jurl()
.url("https://api.spotify.com/v1/artists/not-an-artist")
.go();
if (jurl.getResponseCode() == 200) {
SpotifyArtist artist3 = jurl.getResponseJsonObject(SpotifyArtist.class);
} else {
// ...
}
Jurl also uses Jackson to serialize JSON request bodies. Note also the calls to .method()
to designate "POST" and .header()
to set request headers.
public static class EatStreetSigninRequest {
public String email;
public String password;
}
@JsonIgnoreProperties(ignoreUnknown = true)
public static class EatStreetUser {
public String email;
public String phone;
public String api_key;
}
EatStreetSigninRequest signinRequest = new EatStreetSigninRequest();
signinRequest.email = "[email protected]";
signinRequest.password = "hunter2";
EatStreetUser user = new Jurl()
.url("https://eatstreet.com/publicapi/v1/signin")
.method("POST")
.header("X-Access-Token", "__API_EXPLORER_AUTH_KEY__")
.bodyJson(signinRequest)
.go()
.getResponseJsonObject(EatStreetUser.class);
Jurl uses Java Future
s to make requests asynchronously.
Future<Jurl> asyncJurl = new Jurl()
.url("https://api.spotify.com/v1/artists/147jymD5t0TCXW0DbaXry0")
.goAsync();
SpotifyArtist artist4 = asyncJurl.get().getResponseJsonObject(SpotifyArtist.class);
After a request is done, calling newWithCookies()
will return a new Jurl
instance with request cookies pre-filled, to preserve session.
You can call .toCurl()
on a Jurl
instance, it will return a valid unix curl
command, useful for debugging.
- Only UTF-8 encoded character request and response bodies are supported.
param()
calls for POST requests will be x-www-form-urlencoded in the body.bodyJson()
calls will also set theContent-Type
header toapplication/json
.