How to Retrieve Documents

→ "Try it out - API Component "YADB""
→ check GitHub Python calls | Java Script calls | Java calls | Postman collection


This "How to" describes various ways to retrieve documents (objects) using the yuuvis® API. Note that to be able to access documents (objects), they must already be imported and stored in the system (Import and Store Documents (Objects)).

Retrieving Documents via Object ID

The direct access to a document (object) takes place via its unique identifier - the objectId.

To retrieve the current version of the document's metadata in JSON format, you send a GET request to the URL /dms-core/objects/{objectId} (Get document metadata by ID endpoint).

Retrieving Current metadata
String objectId = "1234567890"; //example-objectId
Request metadataRequest = new Request.Builder()
        .header("Ocp-Apim-Subscription-Key", key)
        .url(baseUrl+ "/dms-core/objects/" + objectId)
        .get().build();
Response metadataResponse = client.newCall(metadataRequest).execute();
String metadataResponseString = metadataResponse.body().string();

To retrieve the current content file of a document (object), you send a GET request to the URL /dms-core/objects/{objectId}/contents/file (GET document content by ID endpoint).

Retrieving Current Content File
Request contentRequest = new Request.Builder()
        .header("Ocp-Apim-Subscription-Key", key)
        .url(baseUrl+ "/dms-core/objects/" + objectId + "/contents/file")
        .get().build();

If you want to request a specific version of the document, the endpoint to be called for the documents' metadata change to /dms-core/objects/{objectId}/versions/{versionNr} and for the documents' content to /dms-core/objects/{objectId}/versions/{versionNr}/contents/file. Please refer to "Updating Documents | Versioning"

Responses

Status Code Meaning
200 OK
401 Unauthorized
404 Not Found

Retrieving Documents via Search Endpoint

The yuuvis® API provides a search endpoint (/dms-core/objects/search, "Search documents by search query" endpoint) that can process search queries written in the proprietary CMIS-Based Query Language. The search query is sent to the search endpoint in JSON format in the body of a POST request.

Query in JSON Format
{
	"query": {
		"maxItems": 50,
		"statement": "SELECT * FROM enaio:object WHERE CONTAINS('European') AND Name Like 'E%'",
		"skipCount": 0
	}
}

This example query searches for all documents (objects) of type enaio:object whose content contains the string "European" and whose value of attribute Name begins with the character 'E'.

Status Code Meaning
200 OK
401 Unauthorized
422 Invalid Query

To create such a query object programmatically, a JSON library is needed to create the query JSON. You can use org.json, and add the following block to your Maven dependencies in the pom.xml of the Java project:

pom.xml
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20180813</version>
</dependency>

Now you can implement a method createQueryJSON(String statement, int skipCount, int maxItems) that creates a query object and returns it as a string. Send the string to the search endpoint in the request body of a POST request:

Retrieving Documents via Search Endpoint
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 enaio:object WHERE CONTAINS('Europan') AND Name Like 'E%'", 0, 50);
Request attributeSearchRequest = new Request.Builder()
        .header("Ocp-Apim-Subscription-Key", key)
        .url(baseUrl + "/dms-core/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 documents (objects) with metadata matching the search query, which can also be an empty list.