1. Overview
In this tutorial, we will send search requests to the core API.
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 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.