Introduction
JRest provides an opportunity to create an API contract via a Java Interface
public interface GithubInterface {
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user);
}
The JRest class can be used to build an implementation of your GithubInterface
GithubInterface githubInterface = new JRest.APIBuilder("https://postman-echo.com")
.build(TestPostmanEchoAPIInterface.class);
APIResponse<Map<String, Object>> response = githubInterface.listRepos("testUser");
One can either make a Synchronous or Asynchronous request either via Callback or via Future
Synchronous Call
APIResponse<Map<String, Object>> response = githubInterface.listRepos("testUser");
Asynchronous Call via Callback
public interface GithubInterface {
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
void listReposWithCallback(@Path(value = "user") String user, APICallBack<Map<String, Object>>);
}
githubInterface.listReposWithCallback("testUser",new APICallBack<Void, ApiResponse>() {
@Override
public void callBackOnSuccess(APIResponse<Map<String, Object>> result) {
System.out.println(myCall.getResponseCode());
}
@Override
public void callBackOnFailure(Throwable e) {
System.out.println("error");
e.printStackTrace();
}
});
Asynchronous Call via Future
public interface GithubInterface {
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
Future<APIResponse<Map<String, Object>>> listReposWithFuture(@Path(value = "user") String user);
}
Future<APIResponse<Map<String, Object>>> response = githubInterface.listReposWithFuture("testUser");
Use annotations to describe the HTTP request:
- URL parameter replacement
- Object conversion to request body
- Query Parameter Support
API Declaration
Annotations on the interface methods and its parameters indicate how a request will be handled.
REQUEST METHOD
Every method must have an REQUEST annotation that provides the request method and relative URL. The relative URL of the resource is specified in the annotation via endpoint and Request type can be specified by the type attribute
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
URL MANIPULATION
A request URL can be updated dynamically using replacement blocks and parameters on the method. A replacement block is an alphanumeric string surrounded by { and }.
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user);
Query Parameters can be added via the @Query Annotation
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user,@Query("sortBy") String sortBy);
Complex Parameters can be represented via the @QueryMap Annotation
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user,@QueryMap Map<String,String> queryMap);
HEADER MANIPULATION
Headers can be added to a API Method in a static manner via Headers annotation
@Headers("X-Foo:Bar")
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user);
Multiple Headers can also be set in a static manner via below
@Headers({
"X-Foo:Bar",
"X-Ping:Pong"
})
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user);
A request Header can also be updated dynamically via the HeaderMap annotation set in the method Parameter
@Headers("X-Foo:Bar")
@REQUEST(endpoint = "/users/{user}/repos",type = HTTP_METHOD.GET)
APIResponse<Map<String, Object>> listRepos(@Path(value = "user") String user,@HeaderMap Map<String, String> header);
Note that the Headers parameters can only be used via a Map
REQUEST BODY
An object can be specified for use as an HTTP request body with the @Body annotation.
@REQUEST(endpoint = "/users/new",type = HTTP_METHOD.POST)
APIResponse<Map<String, Object>> createUser(@Body User user);
The Object would be converted via Google Gson into the required JSON data while posting