RESTful

OpenKM has a complete API exposed via REST. You can call any API method from any programming language, like Java, PHP, or Python.  This feature makes it possible to create a custom client or integrate with third-party applications like a CRM or a CMS.

Note

These URLs are protected by BASIC authentication, so you must provide a username and password to access them.

You can extend the REST API—more information at Creating your own REST Plugin (extending REST API).

Tip

We encourage you to use our SDKs to access OpenKM via the REST API rather than building your own client; more information:

• The SDK for Java.
• The SDK for .NET.

In most samples, you’ll see parameters named “docId,” “fldId” or “nodeId.” The value of this parameter can be a valid node UUID (since version 7.x, most methods that accept a path have been deprecated).

Tip

Example of a nodeId:

• Using UUID -> “f123a950-0329-4d62-8328-0ff500fd42db”;
• Using path -> “/okm:root/logo.png”

Note

Almost all samples use the curl command; more information is available at the curl tutorial with usage examples.

Sample usage

You can use an HTTP client library or any REST client to try these API methods, which makes this process easier. Or you can use the curl command-line application. For example, you can list the child folders:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   http://localhost:8080/openkm/rest/folders/de7b07c2-e707-4390-b5cc-cae340c8c3e5/children

The result is:

[
  {
    "@type": "folder",
    "created": 1568408949000,
    "lastModified": 1568409037000,
    "path": "/okm:root/test/test",
    "author": "okmAdmin",
    "permissions": 31,
    "uuid": "0fd9f008-27e8-4980-a22b-d71c9a34060a",
    "parent": "de7b07c2-e707-4390-b5cc-cae340c8c3e5",
    "subscribed": false,
    "nodeClass": 0,
    "dispositionCurrentStage": 0,
    "subscriptors": [],
    "keywords": [],
    "categories": [],
    "notes": [],
    "linkTarget": null,
    "actualVersion": {
      "name": "1.1",
      "created": 1568409037000,
      "size": 0,
      "author": "okmAdmin",
      "actual": true,
      "comment": null,
      "checksum": null,
      "action": "PROPERTY_GROUP_ADDED",
      "params": "okg:consulting",
      "uuid": null,
      "parent": "0fd9f008-27e8-4980-a22b-d71c9a34060a"
    },
    "promotedAsRecord": false,
    "hasRelations": false,
    "description": null,
    "restricted": false,
    "nodeClassChildren": [],
    "metadataLabel": null,
    "hasChildren": false,
    "style": 0
  }
]

In this case, you can see the result in JSON format.

This is a Java client for the same call:  

package com.openkm;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.PasswordAuthentication;
import java.net.URL;

public class JavaRestClient {

    public static void main(String[] args) throws Exception {
        try {
            String fldUuid = "de7b07c2-e707-4390-b5cc-cae340c8c3e5";
            URL url = new URL("http://localhost:8080/openkm/rest/folders/" + fldUuid + "/children");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");

            Authenticator.setDefault(new Authenticator() {
                protected PasswordAuthentication getPasswordAuthentication() {
                    return new PasswordAuthentication("okmAdmin", "admin".toCharArray());
                }
            });

            if (conn.getResponseCode() == 200) {
                BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));
                System.out.println("Output from Server .... \n");
                String output;

                while ((output = br.readLine()) != null) {
                    System.out.println(output);
                }
            } else {
                System.err.println("Failed : HTTP error code : " + conn.getResponseCode());
            }

            conn.disconnect();
        } catch (MalformedURLException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Folder samples

Create a new folder:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   -X POST -H "Content-Type: application/json" -d 'newfolder' \
   http://localhost:8080/openkm/rest/folders/parents/fe239ae2-4d25-4d87-88b2-924d03b87faa

Rename a folder:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
  -X PUT -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'newName=test2' \
 http://localhost:8080/openkm/rest/folders/fe239ae2-4d25-4d87-88b2-924d03b87faa/name

Document samples

To create a document, we need to provide the document binary data:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   -X POST -F content=newDoc.txt -F content=@/home/openkm/doc1.txt \
   http://localhost:8080/openkm/rest/documents/parents/fe239ae2-4d25-4d87-88b2-924d03b87faa

Or from an HTML form:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document Upload</title>
</head>
<body>
    <form method="POST" enctype="multipart/form-data"
          action="http://localhost:8080/openkm/rest/documents/parents/fe239ae2-4d25-4d87-88b2-924d03b87faa">
      Select file: <input type="file" name="content" size="45"/><br/>
      <input type="submit" value="Upload" />
    </form>
</body>
</html>

To download it:  

$ curl -u okmAdmin:admin \
  http://localhost:8080/openkm/rest/documents/dab830ea-2fa8-439f-837e-de15409d88b9/content

Search samples

Search with parameters:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/openkm/rest/search?keyword=test&name=doc*&mimeType=application/pdf

Search with metadata:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/openkm/rest/search?keyword=test&property='okp:consulting.name=alfa'

Security samples

Show granted users:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
  http://localhost:8080/openkm/rest/auth/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/permissions/users

Show granted roles:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
  http://localhost:8080/openkm/rest/auth/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/permissions/roles

Add a grant:

$ curl -v -u okmAdmin:admin -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d userId=sochoa -d permissions=15 -d recursive=false \
  http://localhost:8080/openkm/rest/auth/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/permissions/us

Revoke a grant:

$ curl -v -u okmAdmin:admin -X DELETE -H "Content-Type: application/x-www-form-urlencoded" \
  -d permissions=15 -d recursive=false \
  http://localhost:8080/openkm/rest/auth/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/permissions/users/sochoa

Metadata samples

The metadata group definition used in the samples:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.10//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.10.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Name" type="text" name="okp:consulting.name" >
      <validator type="req"/>
    </input>
    <textarea label="Comment" name="okp:consulting.comment" >
      <validator type="req"/>
    </textarea>
  </property-group>
</property-groups>

Add a metadata group:

$ curl -u okmAdmin:admin -H "Accept: application/json"  \
  -X POST -H "Content-Type: application/json"
 -d '{"properties":[{"name":"okp:consulting.comment","value":"new comment"},{"name":"okp:consulting.name","value":"new name"},{"name":"okp:consulting.date","value":"20190917163517"}],"grpName":"okg:consulting"}' \
 http://localhost:8080/openkm/rest/propertygroups/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/groups

Set metadata group values:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
  -X PUT -H "Content-Type: application/json" \
  -d '[{"name":"okp:consulting.comment","value":"set comment"},{"name":"okp:consulting.name","value":"set name"},{"name":"okp:consulting.date","value":"20190917164717"}]' \
 http://localhost:8080/openkm/rest/propertygroups/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/groups/okg:consulting/properties

Notes samples

Create a note:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'text=Hello, world!' \
   http://localhost:8080/openkm/rest/note/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa

Conversion samples

With the conversion feature of the OpenKM API, you can convert, for example, a document from Microsoft Word format to PDF, among other available conversion types.

Convert a doc file to PDF:

$ curl -u okmAdmin:admin -F content=@sample.doc -o sample.pdf \
  http://localhost:8080/openkm/rest/conversion/doc/pdf

Or from an HTML form:

<html>
  <body>
    <form method="POST" enctype="multipart/form-data"
          action="http://localhost:8080/openkm/services/rest/conversion/doc2pdf">
      Select file: <input type="file" name="content" size="45"/><br/>
      <input type="submit" value="Convert" />
    </form>
  </body>
</html>

Convert a doc file to txt:

$ curl -u okmAdmin:admin -F content=@sample.doc http://localhost:8080/openkm/rest/conversion/doc/txt

Convert an image file to txt:

$ curl -u okmAdmin:admin -F content=@sample.tif http://localhost:8080/rest/rest/conversion/img/txt

REST plugin samples

With the REST plugin, you can extend the default REST API.

$ curl -u okmAdmin:admin -G \
    -H "Accept: application/json" \
    --data-urlencode "className=com.openkm.plugin.rest.TestRestPlugin" \
    --data-urlencode 'param={"key":"key1","value":"value1"}' \
    http://localhost:8080/openkm/rest/plugins