One of the most common tasks is to consume RESTful web services in Java, in this post I will explain a design pattern using Jersey client.
Step 1 : Configuration
The project will include the dependencies described in the following pom.xml, as you can see there we have the following support:
- Jackson : For serialization and deserialization
- slf4j : For logging
- failsafe: Api for retry logic
And at the end we can see we have the maven-compiler-plugin to define the Java version we are using.
Step 2 : Creating an abstract client
The next step will be to create an AbstractClient, you can use it in any rest client you want, lets see and analyze the code:
import java.io.IOException;
import java.util.Optional;
import java.util.concurrent.TimeUnit;
import java.util.logging.Logger;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;
import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.JsonMappingException;
import net.jodah.failsafe.Failsafe;
import net.jodah.failsafe.RetryPolicy;
/**
* @author raidentrance
*
*/
public abstract class AbstractClient {
private String url;
private String contextPath;
private RetryPolicy defaultRetryPolicy;
private static final Logger log = Logger.getLogger(AbstractClient.class.getName());
public AbstractClient(String url, String contextPath) {
this.url = url;
this.contextPath = contextPath;
}
public AbstractClient(String url, String contextPath, int maxRetries, int delay, TimeUnit unit) {
this.url = url;
this.contextPath = contextPath;
defaultRetryPolicy = new RetryPolicy().retryIf((Response resp) -> {
if (resp != null) {
return resp.getStatusInfo().getFamily() == Status.Family.SERVER_ERROR;
} else {
return false;
}
}).withDelay(delay, unit).withMaxRetries(maxRetries);
}
protected WebTarget createClient(String path) {
String assembledPath = assembleEndpoint(path);
Client client = ClientBuilder.newClient();
return client.target(assembledPath);
}
private String assembleEndpoint(String path) {
String endpoint = url.concat(contextPath).concat(path);
log.info(String.format("Calling endpoint %s", endpoint));
return endpoint;
}
/**
* Execute a GET http request over the endpoint received with the content
* type specified
*
* @param endpoint
* Defines the endpoint that will be executed
* @param type
* Defines the content type it can be JSON,XML, etc
* @return A response object with the entity response and the Http status
*/
protected Response get(String endpoint, String type) {
WebTarget client = createClient(endpoint);
Optional result = getDefaultRetryPolicy();
if (result.isPresent()) {
return Failsafe.with(result.get()).get((response) -> client.request(type).get());
} else {
return client.request(type).get();
}
}
/**
* Execute a PUT request over the endpoint received with the content type
* specified and sending the object received in the body
*
* @param endpoint
* Endpoint will be executed
* @param type
* Defines the content type, it can be JSON, XML, etc
* @param entity
* Object will be sent in the body of the request
* @return A response object with the entity response and the Http status
*/
protected Response put(String endpoint, String type, Object entity) {
WebTarget client = createClient(endpoint);
Optional result = getDefaultRetryPolicy();
if (result.isPresent()) {
return Failsafe.with(result.get()).get((response) -> client.request(type).put(Entity.entity(entity, type)));
} else {
return client.request(type).put(Entity.entity(entity, type));
}
}
/**
* Execute a POST request over the endpoint received with the content type
* specified and sending the object received in the body
*
* @param endpoint
* Endpoint will be executed
* @param type
* Defines the content type, it can be JSON, XML, etc
* @param entity
* Object will be sent in the body of the request
* @return A response object with the entity response and the Http status
*/
protected Response post(String endpoint, String type, Object entity) {
WebTarget client = createClient(endpoint);
Optional result = getDefaultRetryPolicy();
if (result.isPresent()) {
return Failsafe.with(result.get())
.get((response) -> client.request(type).post(Entity.entity(entity, type)));
} else {
return client.request(type).put(Entity.entity(entity, type));
}
}
/**
* If there is a default retry policy it will be returned
*
* @return
*/
public Optional getDefaultRetryPolicy() {
return (defaultRetryPolicy != null) ? Optional.of(defaultRetryPolicy) : Optional.empty();
}
/**
* Modify the current default retry policy
*
* @param maxRetries
* Number of times that it will retry until a successful request
* @param delay
* The time that will wait until the next attempt
* @param unit
* Unit of the time of the delay, it can be in seconds, minutes,
* etc.
*/
public void setDefaultRetryPolicy(int maxRetries, int delay, TimeUnit unit) {
defaultRetryPolicy = new RetryPolicy()
.retryIf((Response resp) -> resp.getStatusInfo().getFamily() == Status.Family.SERVER_ERROR)
.withDelay(delay, unit).withMaxRetries(maxRetries);
}
/**
* Get a Response and Parse to type T. if the response is not 200 throw
* Exception
*
* @param response
* the HTTP response
* @param entityType
* is a generic type that the function will return.
* @param
* The Generic Type that the method is returing
* @return T
* @throws Exception
* if a problem occurs
* @throws IOException
* @throws JsonMappingException
* @throws JsonParseException
*/
protected abstract T parseResponse(Response response,TypeReference entityType) throws Exception;
}
Now lets analyze the class:
- Constructors: There are two ways to construct our object
- Only with the url and the context path
- Including also the maxRetries, delay and TimeUnit
-
createClient(String path) : Will create a Jersey client used to consume the api’s.
-
assembleEndpoint(String path) : Based on the Endpoint will build the url we are going to consume.
-
Response get(String endpoint, String type) : Generic get method that receives two parameters an endpoint and a type.
-
Response put(String endpoint, String type, Object entity): Generic put method that receives two parameters an endpoint and a type.
-
Response post(String endpoint, String type, Object entity): Generic post method that receives two parameters an endpoint and a type.
-
Optional getDefaultRetryPolicy() : if the parameters maxRetries, delay and TimeUnit were assigned it will return the retry policy to use.
-
setDefaultRetryPolicy(int maxRetries, int delay, TimeUnit unit): You can use it if you want to change the default policy .
-
abstract T parseResponse(Response response,TypeReference entityType) throws Exception: Your implementation has to override the parseResponse method to define how it will translate the response.
Step 3 : Define a class to set all the endpoints
Once we have our abstract class, we have to define an endpoints class, in our case it will be ApplicationEndpoints, it will centralize all the endpoints used in the client.
/**
* @author raidentrance
*
*/
public class ApplicationEndpoints {
private static final String TICKER = "/ticker";
private ApplicationEndpoints() {
}
public static String getTickers() {
return TICKER;
}
public static String getTickerByBook(String book) {
return TICKER.concat("?book=").concat(book);
}
}
In this case we are using the api of bitso to get prices of crypto currencies, you can see the documentation here and query the api in the url https://api.bitso.com/v3/ticker/
Step 4 : Defining the error model
Now we have to handle errors, to do it we will analyze the api we are querying, lets see the error model:
{
"success": false,
"error": {
"code": "0301",
"message": "Unknown OrderBook xrp_mxnq"
}
}
Now we have to translate it to java classes.
ErrorCode.java
import java.io.Serializable;
/**
* @author raidentrance
*
*/
public class ErrorCode implements Serializable {
private String code;
private String message;
private static final long serialVersionUID = 1735206115257033120L;
public ErrorCode() {
}
public ErrorCode(String code, String message) {
super();
this.code = code;
this.message = message;
}
public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}
ErrorMessage.java
import java.io.Serializable;
/**
* @author raidentrance
*
*/
public class ErrorMessage implements Serializable {
private boolean success;
private ErrorCode error;
private static final long serialVersionUID = -8921696489057035324L;
public ErrorMessage() {
}
public ErrorMessage(boolean success, ErrorCode error) {
this.success = success;
this.error = error;
}
public boolean isSuccess() {
return success;
}
public void setSuccess(boolean success) {
this.success = success;
}
public ErrorCode getError() {
return error;
}
public void setError(ErrorCode error) {
this.error = error;
}
}
Once we have both classes we are able to deserialize the errors to java objects, now we just need to create an exception to propagate the errors.
import com.raidentrance.rest.error.model.ErrorMessage;
/**
* @author raidentrance
*
*/
public class ServiceException extends Exception {
private ErrorMessage errorMessage;
private static final long serialVersionUID = -7898115956660992515L;
public ServiceException(ErrorMessage errorMessage) {
this.errorMessage = errorMessage;
}
public ErrorMessage getErrorMessage() {
return errorMessage;
}
}
The ServiceException will be thrown when an error happens and it will contain the error message we receive from the api.
Step 5 : Creating the model
We defined the model for the errors, but now we have to define the model for our api’s, in this case we will be reading tickers with the following structure:
Payload.java
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* @author raidentrance
*
*/
public class Payload {
@JsonProperty("high")
private String high;
@JsonProperty("last")
private String last;
@JsonProperty("created_at")
private String createdAt;
@JsonProperty("book")
private String book;
@JsonProperty("volume")
private String volume;
@JsonProperty("vwap")
private String vwap;
@JsonProperty("low")
private String low;
@JsonProperty("ask")
private String ask;
@JsonProperty("bid")
private String bid;
public String getHigh() {
return high;
}
public void setHigh(String high) {
this.high = high;
}
public String getLast() {
return last;
}
public void setLast(String last) {
this.last = last;
}
public String getCreatedAt() {
return createdAt;
}
public void setCreatedAt(String createdAt) {
this.createdAt = createdAt;
}
public String getBook() {
return book;
}
public void setBook(String book) {
this.book = book;
}
public String getVolume() {
return volume;
}
public void setVolume(String volume) {
this.volume = volume;
}
public String getVwap() {
return vwap;
}
public void setVwap(String vwap) {
this.vwap = vwap;
}
public String getLow() {
return low;
}
public void setLow(String low) {
this.low = low;
}
public String getAsk() {
return ask;
}
public void setAsk(String ask) {
this.ask = ask;
}
public String getBid() {
return bid;
}
public void setBid(String bid) {
this.bid = bid;
}
@Override
public String toString() {
return "Payload [high=" + high + ", last=" + last + ", createdAt=" + createdAt + ", book=" + book + ", volume="
+ volume + ", vwap=" + vwap + ", low=" + low + ", ask=" + ask + ", bid=" + bid + "]";
}
}
Ticker.java
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* @author raidentrance
*
*/
public class Ticker {
@JsonProperty("success")
private boolean success;
@JsonProperty("payload")
private Payload payload;
public boolean isSuccess() {
return success;
}
public void setSuccess(boolean success) {
this.success = success;
}
public Payload getPayload() {
return payload;
}
public void setPayload(Payload payload) {
this.payload = payload;
}
@Override
public String toString() {
return "Ticker [success=" + success + ", payload=" + payload + "]";
}
}
TickerList.java
import java.util.List;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* @author maagapi
*
*/
public class TickerList {
@JsonProperty("success")
private boolean success;
@JsonProperty("payload")
private List payload;
public boolean isSuccess() {
return success;
}
public void setSuccess(boolean success) {
this.success = success;
}
public List getPayload() {
return payload;
}
public void setPayload(List payload) {
this.payload = payload;
}
@Override
public String toString() {
return "TickerList [success=" + success + ", payload=" + payload + "]";
}
}
Once we defined the model, we can call the api’s.
Step 6 : Creating the RestClient
The last step will be create the RestClient this class will be the responsible to join all the pieces:
import java.io.IOException;
import java.io.StringReader;
import java.util.concurrent.TimeUnit;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.raidentrance.rest.commons.AbstractClient;
import com.raidentrance.rest.endpoints.ApplicationEndpoints;
import com.raidentrance.rest.error.exception.ServiceException;
import com.raidentrance.rest.error.model.ErrorCode;
import com.raidentrance.rest.error.model.ErrorMessage;
import com.raidentrance.rest.model.Ticker;
import com.raidentrance.rest.model.TickerList;
/**
* @author raidentrance
*
*/
public class RestClient extends AbstractClient {
private static final Logger log = LoggerFactory.getLogger(RestClient.class);
public RestClient(String url, String contextPath) {
super(url, contextPath);
}
public RestClient(String url, String contextPath, int maxRetries, int delay, TimeUnit unit) {
super(url, contextPath, maxRetries, delay, unit);
}
public TickerList getTickers() throws Exception {
return parseResponse(get(ApplicationEndpoints.getTickers(), MediaType.APPLICATION_JSON),
new TypeReference() {
});
}
public Ticker getTickerByBook(String book) throws Exception {
return parseResponse(get(ApplicationEndpoints.getTickerByBook(book), MediaType.APPLICATION_JSON),
new TypeReference() {
});
}
@Override
protected T parseResponse(Response response, TypeReference entityType) throws ServiceException {
int status = response.getStatus();
log.info("Status {}", status);
if (response.getStatusInfo().getFamily() == Status.Family.SUCCESSFUL) {
try {
return new ObjectMapper().readValue(new StringReader(response.readEntity(String.class)), entityType);
} catch (IOException e) {
throw new ServiceException(
new ErrorMessage(false, new ErrorCode("1000", "Request couldn't be processed")));
}
} else {
throw new ServiceException(response.readEntity(ErrorMessage.class));
}
}
}
As you can see now just with one line of code we make an http request, handle the retries and parse the response.
Step 7 : Test it
In other posts we will show how to write unit tests for this kind of components, now lets just create a main method to test it:
public static void main(String[] args) throws Exception {
RestClient client = new RestClient("https://api.bitso.com", "/v3", 3, 3, TimeUnit.SECONDS);
TickerList tickers = client.getTickers();
log.info("Getting tickers ");
for (Payload payload : tickers.getPayload()) {
log.info(payload.toString());
}
log.info("Getting ripple ticker");
Ticker ripple = client.getTickerByBook("xrp_mxn");
log.info(ripple.toString());
log.info("Not existing ticker");
Ticker alex = client.getTickerByBook("alex");
log.info(alex.toString());
}
If we execute the code we will see the following output (It can be different according with the ripple price :P):
mar 12, 2018 5:09:02 PM com.raidentrance.rest.commons.AbstractClient assembleEndpoint INFORMACIÓN: Calling endpoint https://api.bitso.com/v3/ticker [main] INFO com.raidentrance.rest.RestClient - Status 200 [main] INFO com.raidentrance.rest.RestClient - Getting tickers [main] INFO com.raidentrance.rest.RestClient - Payload [high=187000.00, last=174233.33, createdAt=2018-03-12T23:09:02+00:00, book=btc_mxn, volume=244.45021807, vwap=175921.68443739, low=167000.00, ask=174216.10, bid=173560.15] [main] INFO com.raidentrance.rest.RestClient - Payload [high=13957.02, last=13388.86, createdAt=2018-03-12T23:09:02+00:00, book=eth_mxn, volume=340.00979171, vwap=13198.66244190, low=13000.00, ask=13388.86, bid=13052.63] [main] INFO com.raidentrance.rest.RestClient - Payload [high=0.00008704, last=0.00008600, createdAt=2018-03-12T23:09:02+00:00, book=xrp_btc, volume=44561.33425456, vwap=0.00008500, low=0.00008312, ask=0.00008678, bid=0.00008601] [main] INFO com.raidentrance.rest.RestClient - Payload [high=15.75, last=14.92, createdAt=2018-03-12T23:09:02+00:00, book=xrp_mxn, volume=688462.85426546, vwap=15.12242330, low=14.75, ask=15.08, bid=14.92] [main] INFO com.raidentrance.rest.RestClient - Payload [high=0.07688000, last=0.07550000, createdAt=2018-03-12T23:09:02+00:00, book=eth_btc, volume=56.85901332, vwap=0.07569318, low=0.07430000, ask=0.07641999, bid=0.07551000] [main] INFO com.raidentrance.rest.RestClient - Payload [high=0.11879867, last=0.11421000, createdAt=2018-03-12T23:09:02+00:00, book=bch_btc, volume=34.25655963, vwap=0.11580909, low=0.11336268, ask=0.11589999, bid=0.11430000] [main] INFO com.raidentrance.rest.RestClient - Payload [high=0.02011990, last=0.01965100, createdAt=2018-03-12T23:09:02+00:00, book=ltc_btc, volume=151.10013187, vwap=0.01966700, low=0.01942300, ask=0.01990000, bid=0.01965010] [main] INFO com.raidentrance.rest.RestClient - Payload [high=3700.00, last=3404.61, createdAt=2018-03-12T23:09:02+00:00, book=ltc_mxn, volume=2501.73845947, vwap=3466.53149080, low=3392.80, ask=3465.97, bid=3404.71] [main] INFO com.raidentrance.rest.RestClient - Getting ripple ticker mar 12, 2018 5:09:03 PM com.raidentrance.rest.commons.AbstractClient assembleEndpoint INFORMACIÓN: Calling endpoint https://api.bitso.com/v3/ticker?book=xrp_mxn [main] INFO com.raidentrance.rest.RestClient - Status 200 [main] INFO com.raidentrance.rest.RestClient - Ticker [success=true, payload=Payload [high=15.75, last=14.92, createdAt=2018-03-12T23:09:03+00:00, book=xrp_mxn, volume=688462.85426546, vwap=15.12242330, low=14.75, ask=15.08, bid=14.92]] [main] INFO com.raidentrance.rest.RestClient - Not existing ticker mar 12, 2018 5:09:03 PM com.raidentrance.rest.commons.AbstractClient assembleEndpoint INFORMACIÓN: Calling endpoint https://api.bitso.com/v3/ticker?book=alex [main] INFO com.raidentrance.rest.RestClient - Status 400 Exception in thread "main" com.raidentrance.rest.error.exception.ServiceException at com.raidentrance.rest.RestClient.parseResponse(RestClient.java:68) at com.raidentrance.rest.RestClient.getTickerByBook(RestClient.java:51) at com.raidentrance.rest.RestClient.main(RestClient.java:83)
As you can see we are testing the following cases:
- Get the price of all the crypto currencies
- Get the prices of one crypto currency
- Ask for a price that doesn’t exist and throw an exception with the message.
You can find all the code of this post in the following repository https://github.com/raidentrance/rest-jersey-client.
If you get an SunCertPathBuilderException: unable to find valid certification path to requested target remember that you have to install the certificate to do https requests you can see a guide about how to do it here.
If you like our posts follow us in our social networks https://twitter.com/geeks_mx y https://www.facebook.com/geeksJavaMexico/.
Autor: Alejandro Agapito Bautista
Twitter: @raidentrance
Contact: raidentrance@gmail.com
