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 the REST API).

Tip

We encourage using our SDKs to access OpenKM via the REST API instead of building your own client; more information:

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

In almost all samples, you’ll see parameters named “docId,” “fldId” or “nodeId.” The value of this parameter can be a valid node UUID (from version 7.x, we have deprecated almost all methods where the path can be used).

Tip

Example of 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 in the curl tutorial with examples of usage.

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 a folder’s children:

$ 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

Alternatively, 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>



 Select file:
 

">

And now 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

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

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

Alternatively, 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