1. Overview
In this tutorial, we will discuss various ways to retrieve objects via the Core API from the yuuvis® API system using an OkHttp3 Java client.
Check out our graphical overview of the architecture which describes the basic use case flow for retrieving content or metadata.
2. Requirements
To work through this tutorial, the following is required:
-
Set-up yuuvis® API system (see installation guide)
-
A user with at least read permissions on a document type in the system (see tutorial for permissions)
-
Simple Maven project
3. Maven Configuration
Our Java client will submit its requests to the Core API using OkHttp 3.12 by Square, Inc. Therefore, the following block must be added to the Maven dependencies in the pom.xml of the project:
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>3.12.0</version>
</dependency>
4. Client Configuration
To interact with the yuuvis® API system via the Core API, we use an OkHttp3 client to send HTTP requests and read their responses.
String baseUrl = "http://127.0.0.1"; //baseUrl of gateway: "http://<host>:<port>"
String username = "clouduser";
String userpassword = "secret";
String tenant = "default";
String auth = java.util.Base64.getEncoder().encodeToString((username + ":" + userpassword).getBytes());
OkHttpClient.Builder builder = new OkHttpClient.Builder();
OkHttpClient client = builder.build();
For more information on setting up the OkHttp3 client with cookie handling, please refer to this login tutorial.
5. Retrieving Documents
To be able to access documents, they must exist in the system. A tutorial for importing documents can be found here.
5.1. Retrieving Documents via Object ID
The direct access to a document takes place via its object ID via GET request to the endpoint /api/dms/objects/{objectId}. The objectId serves as a unique identifier of a document and can be obtained from the response of the API call of an import (see Tutorial for updating documents: Determining the objectId after import).
String objectId = "1234567890"; //example-objectId
Request metadataRequest = new Request.Builder()
.header("Authorization", "Basic " + auth)
.header("X-ID-TENANT-NAME", tenant)
.url(baseUrl+ "/api/dms/objects/" + objectId)
.get().build();
Response metadataResponse = client.newCall(metadataRequest).execute();
String metadataResponseString = metadataResponse.body().string();
The API call response will contain the current version of the objects' metadata in JSON format.
To retrieve the content of an object, a GET request is sent to the endpoint /api/dms/objects/{objectId}/contents/file.
Request contentRequest = new Request.Builder()
.header("Authorization", "Basic " + auth)
.header("X-ID-TENANT-NAME", tenant)
.url(baseUrl+ "/api/dms/objects/" + objectId + "/contents/file")
.get().build();
If a specific version of the document is to be requested, the endpoint to be called for the documents' metadata changes to /api/dms/objects/{objectId}/versions/{versionNr} and for the documents' content to /api/dms/objects/{objectId}/versions/{versionNr}/contents/file. More about this topic can be found in the Updating Documents via Core API tutorial under Versioning.
5.2. Retrieving Documents via Search Endpoint
The Core API provides a search endpoint (/api/dms/objects/search) that can process search queries written in the proprietary Search Query Language. The search query is sent to the search endpoint in JSON format in the body of a POST request.
{
"query": {
"maxItems": 50,
"statement": "SELECT * FROM system:object WHERE CONTAINS('Europan') AND Name Like 'E%'",
"skipCount": 0
}
}
This example query searches for all objects of type enaio:object whose content contains the string Europan and whose value of property Name begins with the character E.
To create such a query object programmatically, a JSON library is needed to create the query JSON. We use org.json, so the following block must be added to the Maven dependencies in the pom.xml of the Java project:
<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20180813</version>
</dependency>
Now we can implement a method createQueryJSON(String statement, int skipCount, int maxItems) that creates a query object and returns it as a string. We send the string to the search endpoint in the request body of a POST request:
public static String createQueryJSON(String statement, int skipCount, int maxItems) {
JSONObject queryObject = new JSONObject();
JSONObject queryAttributes = new JSONObject();
queryAttributes.put("statement", statement);
queryAttributes.put("skipCount", skipCount);
queryAttributes.put("maxItems", maxItems);
queryObject.put("query", queryAttributes);
return queryObject.toString();
}
String query = createQueryJSON("SELECT * FROM system:object WHERE CONTAINS('Europan') AND Name Like 'E%'", 0, 50);
Request attributeSearchRequest = new Request.Builder()
.header("Authorization", "Basic " + auth)
.header("X-ID-TENANT-NAME", tenant)
.url(baseUrl + "/api/dms/objects/search")
.post(RequestBody.create(MediaType.parse("application/json; charset=utf-8"), query))
.build();
Response attributeSearchResponse = client.newCall(attributeSearchRequest).execute();
System.out.println(attributeSearchResponse.body().string());
The expected response is a list of DMS objects with metadata matching the search query, which can also be an empty list.
6. Summary
This tutorial showed how to use an OkHttpClient to retrieve documents via Core API.
A complete code example can be found in this Git repository.