Box Rest API and Java SDK — Getting started and Best Practices
The Box Rest API is a core part for integration scenarios besides the Box Webhooks.
Box supports a lot of languages/frameworks and has built an SDK on top of them.
We have used the Box Java SDK and Box Node SDK in our latest project. In this blog post we will look into the Java SDK.
Box Java SDK
The Box Java SDK is an official supported SDK for the Box Rest API. To get started with it, you can use following resources:
The source code is opensource and can be found on github:
https://github.com/box/box-java-sdk
Hands on
The central class for the Box Library is the BoxAPIConnection for managed users. For integrating a Box service account with server to server authentication you have to use the class BoxDeveloperEditionApiConnection. Only this class makes the JWT authentication in the background for you. (Of course you could do it by hand, but it is already solved for you!)
Before using it you have to create the BoxConfig with important values like the clientId, clientSecret and a public key for the JWT authentication which can be downloaded from your service account in the developer console.
After you got the authentication running, you can use all the provided rest endpoints. The Box library provides a domain object for each endpoint like BoxFolder, BoxTrash or BoxCollaboration.
In our case we want to rename a file in Box.
The BoxFileClient creates a new BoxFile Info object and set the new name on the info object. The statement file.updateinfo(info) will execute a HTTP PUT to Box with the new name to only update the name of the folder. Great- we only need one HTTP call here!
Our experiences with the Java Box SDK so far:
- It is easy to learn because we can also check in the code what happens behind the scenes. The source code is available on Github.
- From an engineering aspect the library misses some separation aspects in some places - domain classes also make requests to the Box rest endpoints. Sometimes it is not clear if an access to a property of a class makes a call to the rest service again. You get used to it and you can check the source code.
- The box Java SDK is currently missing a very important method to get a box folder by path. This method is neither in the official documentation and not mentioned anywhere else. We have found the REST endpoint in the postman collection provided by Box. It means that you can get a folder by path: https://api.box.com/2.0/folders?path=/Newsletter
This capability helped me to implement the use case very easily (instead of navigating through the repository with many rest calls!). But how can I use it when the Box SDK has no prebuilt classes for it?
Fortunately, the Box SDK allows you to reuse the authentication part and make low level HTTP requests . So I was able to use the BoxRequest and BoxResponse objects to use this method with the Box Java SDK. Using BoxRequest and BoxResponse was easy and wrapped the httpconnection handling.
The implementation can look like this - the most important part is to generate a valid http url that the Box platform accepts. We will provide a pull request to the Box Java SDK to integrate this capability.
As you can see the Box Java SDK is very flexible and allows us to extend it with methods before the Box SDK team adopts it and provides it officially.
We have contributed a pull request for it:
https://github.com/box/box-java-sdk/pull/655
Update:
The pull request will not be merged — the API for getting a folder by path is not a stable API yet. So please use it on your own risk!
I hope you have enjoyed my new blog post! The Box SDK for Node will be covered in one of the later blog posts.
