Write a Client Application Using the SDK¶
-
Follow the steps in the Quick Start Guide, to deploy the sample API, subscribe and generate keys.
Info
Access Token
Once the keys are generated, copy the access token. You can use this token to invoke APIs that you subscribe to using the same application.
-
Go to the Developer Portal. Select your API and download the SDK for Java.
-
In this example, you would have downloaded the
PizzaShackAPI_1.0.0_java.zip
file. This file name includes the API name, version, and language of the SDK. Unzip thePizzaShackAPI_1.0.0_java.zip
file.Expand to see the folder structure of the unzipped file...
PizzaShackAPI_1.0.0_java ├── build.gradle ├── build.sbt ├── docs │ ├── DefaultApi.md │ ├── ErrorListItem.md │ ├── Error.md │ ├── MenuItem.md │ └── Order.md ├── git_push.sh ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradle.properties ├── gradlew ├── gradlew.bat ├── pom.xml ├── README.md ├── settings.gradle └── src ├── main │ ├── AndroidManifest.xml │ └── java │ └── org │ └── wso2 │ └── client │ ├── api │ │ ├── ApiCallback.java │ │ ├── ApiClient.java │ │ ├── ApiException.java │ │ ├── ApiResponse.java │ │ ├── auth │ │ │ ├── ApiKeyAuth.java │ │ │ ├── Authentication.java │ │ │ ├── HttpBasicAuth.java │ │ │ ├── HttpBearerAuth.java │ │ │ ├── OAuthFlow.java │ │ │ ├── OAuth.java │ │ │ ├── OAuthOkHttpClient.java │ │ │ └── RetryingOAuth.java │ │ ├── Configuration.java │ │ ├── GzipRequestInterceptor.java │ │ ├── JSON.java │ │ ├── Pair.java │ │ ├── PizzaShackAPI │ │ │ └── DefaultApi.java │ │ ├── ProgressRequestBody.java │ │ ├── ProgressResponseBody.java │ │ └── StringUtil.java │ └── model │ └── PizzaShackAPI │ ├── Error.java │ ├── ErrorListItem.java │ ├── MenuItem.java │ └── Order.java └── test └── java └── org └── wso2 └── client ├── api │ └── PizzaShackAPI │ └── DefaultApiTest.java └── model └── PizzaShackAPI ├── ErrorListItemTest.java ├── ErrorTest.java ├── MenuItemTest.java └── OrderTest.java
-
Build the SDK using maven . When it’s done, you can include this SDK as a dependency in your software project. Details of this maven dependency are included in the README.md file.
Expand to view Maven dependency
<dependency> <groupId>org.wso2</groupId> <artifactId>org.wso2.client.PizzaShackAPI</artifactId> <version>1.0.0</version> <scope>compile</scope> </dependency>
Info
Build using maven
You can build the SDK using the
mvn clean install
command inside the root directory. For more information see Maven Start Guide. -
After creating a maven project, import the following with respect to the SDK. These classes will be accessible from the code once the SDK is built using maven and will be included as maven dependencies in the project.
import org.wso2.client.api.ApiClient; import org.wso2.client.api.PizzaShackAPI.DefaultApi; import org.wso2.client.model.PizzaShackAPI.Menu;
-
Create an instance of the
DefaultApi
object in the java code. This instance is needed to get the API client which handles the operations related to consuming the API, using the resources of the API.DefaultApi defaultApi = new DefaultApi();
-
The API client of the
DefaultApi
object instance is used to set HTTP request headers with the required data. Note that these HTTP request headers might differ from one API to another, depending on the implementation of the API. A sample is shown below.ApiClient apiClient = defaultApi.getApiClient(); apiClient.addDefaultHeader("Accept", "application/json");
-
Include the access token as a header in the API client object, to invoke the API. If the access token you generated above is a JSON Web Token (JWT), you can replace the
accessToken
string with the JWT obtained.String accessToken = "bc392b16-6ce2-3208-9023-8938fbc376ea"; apiClient.addDefaultHeader("Authorization", "Bearer " + accessToken);
Warning
You need an access token to invoke the API. It is important to have a valid subscription before using the SDK, to obtain an access token. Note that the obtained access token has an expiration time.
-
Set the base path to the API client.
The base path for the client application is the production (or sandbox) URL of the API. This will be in the form ofapiClient.setBasePath("http://localhost:8280/pizzashack/1.0.0");
http(s)://<host>:<port>/<context-of-the-api>
. The default ports for HTTP and HTTPS are8280
and8243
respectively.The context of the API can be found from the API Overview in Developer Portal.
-
Once the
ApiClient
object has all the required data, set theApiClient
for the instance of theDefaultApi
object.defaultApi.setApiClient(apiClient);
-
Finally, we can call the available function in the SDK to get the response from the API.
List<MenuItem> menuItems = (List<MenuItem>) defaultApi.menuGet();
MenuItem
is a model class generated with SDK
Complete java code can be found below.
import org.wso2.client.api.ApiClient;
import org.wso2.client.api.ApiException;
import org.wso2.client.api.PizzaShackAPI.DefaultApi;
import org.wso2.client.model.PizzaShackAPI.MenuItem;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class APIClient {
public static void main(String[] args) throws ApiException {
DefaultApi defaultApi = new DefaultApi();
String accessToken = "bc392b16-6ce2-3208-9023-8938fbc376ea";
Map<String, String> headers = new HashMap<String, String>();
headers.put("Accept", "application/json");
headers.put("Authorization", "Bearer " + accessToken);
ApiClient apiClient = defaultApi.getApiClient();
apiClient.addDefaultHeader("Accept", "application/json");
apiClient.addDefaultHeader("Authorization", "Bearer " + accessToken);
apiClient.setLenientOnJson(true);
apiClient.setBasePath("http://localhost:8280/pizzashack/1.0.0");
defaultApi.setApiClient(apiClient);
List<MenuItem> menuItems = (List<MenuItem>) defaultApi.menuGet();
System.out.println(menuItems);
}
}
Expand to see the pom file
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.pizzashack.client</groupId>
<artifactId>pizzashack-api</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<dependency>
<groupId>org.wso2</groupId>
<artifactId>org.wso2.client.PizzaShackAPI</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
</dependencies>
</project>
Writing a Client Application using the SDK with a renewable access token¶
The previous custom client application explains a simple example that uses a hard coded access token when sending the request. However, in real use cases, we can't simply hard code the access token as it expires after a specific period.
The following example solves the latter mentioned issue by renewing and auto-generating access tokens before sending the API request. In addition, this example also supports regenerating the token and retrying the request upon failure. This custom client application uses an Interceptor that is plugged-in to the client in order to achieve the latter mentioned customization.
Complete java code is as follows.
import com.squareup.okhttp.Interceptor;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import org.wso2.client.api.ApiClient;
import org.wso2.client.api.ApiException;
import org.wso2.client.api.PizzaShackAPI.DefaultApi;
import org.wso2.client.model.PizzaShackAPI.MenuItem;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class APIClient {
public static void main(String[] args){
// Creates an interceptor that intercepts every requests sent by the client to include the Authorization header
Interceptor renewTokenInterceptor = new Interceptor() {
String accessToken = null;
public Response intercept(Chain chain) throws IOException {
// If there is an access token already, use it for the next request, otherwise generate a token
if (accessToken == null) {
getAccessToken();
}
// Send the original request with the Authorization header added and get the response
Request originalRequest = chain.request().newBuilder().addHeader("Authorization", accessToken).build();
Response response = chain.proceed(originalRequest);
// If the response fails, retry the request with a new access token
if (!response.isSuccessful()) {
//Closing the previous response.
response.close();
//Getting the new access token.
getAccessToken();
//Initiating the API request with the access token.
Request newRequest = originalRequest.newBuilder().removeHeader("Authorization")
.addHeader("Authorization", accessToken).build();
//Capture the response
response = chain.proceed(newRequest);
}
return response;
}
private void getAccessToken() throws IOException {
// Implement this method to call the token API and retrieve the access token
accessToken = "Bearer " + // set access token here
}
};
DefaultApi defaultApi = new DefaultApi();
ApiClient apiClient = defaultApi.getApiClient();
// Set the interceptor to the client and generate a new OKHTTPClient
OkHttpClient okHttpClient = apiClient.getHttpClient().newBuilder().addInterceptor(renewTokenInterceptor).build();
apiClient.setHttpClient(okHttpClient);
apiClient.addDefaultHeader("Accept", "application/json");
apiClient.setLenientOnJson(true);
//parse the base path
apiClient.setBasePath("http://localhost:8280/pizzashack/1.0.0");
List<MenuItem> menuItems = (List<MenuItem>) defaultApi.menuGet();
System.out.println(menuItems);
}
}
Expand to see the pom file
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.pizzashack.client</groupId>
<artifactId>pizzashack-api</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<dependency>
<groupId>org.wso2</groupId>
<artifactId>org.wso2.client.PizzaShackAPI</artifactId>
<version>1.0.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>com.squareup.okhttp</groupId>
<artifactId>okhttp</artifactId>
<version>2.7.5</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>com.squareup.okhttp</groupId>
<artifactId>logging-interceptor</artifactId>
<version>2.7.5</version>
<scope>compile</scope>
</dependency>
</dependencies>
</project>