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.

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

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

We encourage using our SDKs for accessing OpenKM across REST API rather than you building your client; more information:

The SDK for Java of SDK for JAVA.
The SDK for .NET of SDK for .NET.

On almost 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 methods where the path can be used ).

Example of nodeId:

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

Almost all samples use the command curl, more information at 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 eases this process. Or you can use the curl command-line application. For example, you can list the children's 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 also 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>

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

With the conversion feature from the OpenKM API, you can convert, for example, a document from MS Office Word format 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

Or also 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

Table of contents [ Hide Show ]

Sample usage
Folder samples
Document samples
Search samples
Security samples
Metadata samples
Notes samples
Conversion samples

OpenKM 7.1