Java SDK: Calling methods and handling errors

Java SDK: Calling methods and handling errors

Calling methods

Making API calls through the Java SDK requires calling defined methods in classes in the com.docusign.esign namespaces. Each of these classes corresponds to a group of endpoints that are used for specific feature areas related to the eSignature REST API.

For any eSignature REST API resource, you may perform:

• Two methods at the resource data set level: GET and POST methods on a given resource. These raw API calls correspond to equivalent list and create API Reference methods, i.e. Java SDK methods listBrands and createBrand.

• Three methods at a specific resource data set row (a single record): GET, PUT, and DELETE methods on a single record. These raw API calls correspond to equivalent get, update, and delete API object methods, i.e. Java SDK methods getBrand, updateBrand, and deleteBrand. Note that resource data set row operations require a specific resource identifier such as a brandId GUID.

Within the context of the Java SDK, each specific REST endpoint contains different methods that can be used to modify the underlying object models. As an example, here are four methods that can be used to interact with the AccountsApi Brand object:

    AccountsApi.createBrand(accountId, brand);
    AccountsApi.getBrand(accountId, brandId);
    AccountsApi.updateBrand(accountId, brandId, brand);
    AccountsApi.deleteBrand(accountId, brandId);

The return type for the object will change. In the example above, all return types for these methods, with the exception of deleteBrand, use the Brand object type. When working with similar methods such as listBrands, though the underlying individual components are similar or even identical, the return type is different.

Methods also contain nested classes that control the various API list options (“arrays” in other programming languages) for the various features of the eSignature API. These nested classes contain their own subsequent getter/setter methods to control their intended features, often for option groups. Here is how you would retrieve the previously applied brand options on a specific brand:

    GetBrandOptions().setIncludeLogos(includeLogos);
    GetBrandOptions().setIncludeExternalReferences(includeExternalReferences);

Finally, methods can have operator overloading (different functions with the same name but different parameters) capabilities. These different methods are used by the Docusign Java SDK client to generate the underlying JSON used by the eSignature REST API.

Handling errors

Error handling is an important part of developing your software. Your code should handle both expected and unexpected errors.

The Java SDK provides an ApiException class that is used for common scenarios where exceptions are thrown. It’s a best practice to catch this exception in your code and inspect the ErrorCode and Message objects which contain useful information that can help you understand the cause of the error.

Common scenarios where the SDK throws an ApiException are:

• Invalid or expired access token.

• HTTP response status code 400 and above. These represent various error messages that are identified by the HTTP layer. Such errors include not authorized (403) errors, which occur as a result of issues with authentication.

• Issues in deserialization of the response JSON. If the JSON sent back by the API cannot be properly deserialized into the Java objects that the SDK is expecting, an ApiException is thrown, and the “bad” JSON is returned in the Message property of the exception.

• JWT issues with either the private RSA key pair or UserId. Since the RequestJWTUserToken method for obtaining an OAuth token using JWT is included in the SDK, an ApiException is thrown if the RSA key or UserId is missing or malformed.

Troubleshooting for common errors has detailed information about causes and resolutions for specific errors.

Obtaining the TraceToken for solving problems via Support

Every API response includes a GUID that can be used to trace it on the back end by Docusign employees, including Support. This GUID is called the trace token. The trace token enables Support staff to find the internal logs in the system related to the API request/response and to get additional information about it. This information may not be directly available to developers with or without the SDK.

To obtain the trace token, you will first need to call the getResponseHeaders method provided by the ApiException class. Here is an example of how to obtain the trace token:

    try {
          // failing code
        } catch (ApiException e) {
System.out.println("Docusign Exception: " + e.getResponseHeaders().get("X-Docusign-TraceToken"));
    }

Note: Some API calls do not return an error, but instead provide error information inside the body of the HTTP response. In this case, you will need to have your code check the data returned from the API to ensure the call was successful.