RESTful

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

Note

If you point your browser to http://localhost:8080/OpenKM/services, you can see all available webservices. At the beginning you’ll see the the SOAP API and at the bottom you will see a Available RESTful services section.

These URLs are protected by BASIC authentication so you need to provide an user 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 using our SDK’s for accessing OpenKM across REST API rather than you build your own client, more information:

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

On almost samples you’ll see parameters named “docId”, “fldId” or “nodeId”. The value of this parameter can be a valid node UUID or path.

Tip

Example of nodeId:

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

Note

Almost all samples use the command curl, more information at curl tutorial with examples of usage.

Sample usage

To try these API methods you can use an HTTP Client library or any REST client which ease this process. Or simply you can use the curl command-line application. For example, you can list the children folders:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   http://localhost:8080/OpenKM/services/rest/folder/getChildren?fldId=3492d662-b58e-417c-85b6-930ad0c6c3cf

The result is:

{"folders":
  {"folder":
    [
      { "author":"okmAdmin",
        "created":"2013-07-29T12:09:11+02:00",
        "path":"\/okm:root\/alfa",
        "permissions":15,
        "subscribed":false,
        "uuid":"6b3e0531-96a9-4675-bb82-215b715b20ca",
        "hasChildren":false },
      { "author":"okmAdmin",
        "created":"2013-07-24T22:56:20+02:00",
        "path":"\/okm:root\/beta",
        "permissions":15,
        "subscribed":false,
        "uuid":"41f1bace-58b4-41a9-b43e-dffc1ac9a954",
        "hasChildren":false}
    ]
  }
}

In this case you can see the result in JSON format. Otherwise you may need an XML output, which can be forced using the ’Accept header:  

$ curl -u okmAdmin:admin -H "Accept: application/xml" \
   http://localhost:8080/OpenKM/services/rest/folder/getChildren?fldId=3492d662-b58e-417c-85b6-930ad0c6c3cf

The result in XML is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<folders>
  <folder>
    <author>okmAdmin</author>
    <created>2013-07-29T12:09:11+02:00</created>
    <path>/okm:root/alfa</path>
    <permissions>15</permissions>
    <subscribed>false</subscribed>
    <uuid>6b3e0531-96a9-4675-bb82-215b715b20ca</uuid>
    <hasChildren>false</hasChildren>
  </folder>
  <folder>
    <author>okmAdmin</author>
    <created>2013-07-24T22:56:20+02:00</created>
    <path>/okm:root/beta</path>
    <permissions>15</permissions>
    <subscribed>false</subscribed>
    <uuid>41f1bace-58b4-41a9-b43e-dffc1ac9a954</uuid>
    <hasChildren>false</hasChildren>
  </folder>
</folders>

This is a Java client for the same call:  

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 = "3492d662-b58e-417c-85b6-930ad0c6c3cf";
            URL url = new URL("http://localhost:8080/OpenKM/services/rest/folder/getChildren?fldId=" + fldUuid);
            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 '/okm:root/newfolder' \
   http://localhost:8080/OpenKM/services/rest/folder/createSimple

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 docPath=/okm:root/newDoc.txt -F content=@newDoc.txt \
   http://localhost:8080/OpenKM/services/rest/document/createSimple

Or also from a HTML form:

<html>
  <body>
    <form method="POST" enctype="multipart/form-data"
          action="http://localhost:8080/OpenKM/services/rest/document/createSimple">
      Select file: <input type="file" name="content" size="45"/><br/>
      Select path: <input type="text" name="docPath" value="/okm:root/newDoc.txt"/><br/>
      <input type="submit" value="Upload" />
    </form>
  </body>
</html>

And now download it:  

$ curl -u okmAdmin:admin \
   http://localhost:8080/OpenKM/services/rest/document/getContent?docId=58f79fa6-fe6e-4f68-8517-68a60898d122

Search samples

Basic search by content:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/OpenKM/services/rest/search/findByContent?content=santo+grial

Basic search by keyword:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/OpenKM/services/rest/search/findByKeywords?keyword=santo\&keyword=grial

Search with parameters:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/OpenKM/services/rest/search/find?content=grial\&mimeType=application/pdf

Search with metadata:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/OpenKM/services/rest/search/find?content=grial\&property='okp:name=alfa'

Security samples

Show granted users:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
  http://localhost:8080/OpenKM/services/rest/auth/getGrantedUsers?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf

Show granted roles:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
  http://localhost:8080/OpenKM/services/rest/auth/getGrantedRoles?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf

Add a grant:

$ curl -v -u okmAdmin:admin -X PUT -H "Content-Type: application/x-www-form-urlencoded" \
  -d user=john -d permissions=15 -d recursive=false -d nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf \
  http://localhost:8080/OpenKM/services/rest/auth/grantUser

Revoke a grant:

$ curl -v -u okmAdmin:admin -X PUT -H "Content-Type: application/x-www-form-urlencoded" \
  -d user=john -d permissions=15 -d recursive=false -d nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf \
  http://localhost:8080/OpenKM/services/rest/auth/revokeUser

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 2.0//EN"
                                 "http://www.openkm.com/dtd/property-groups-2.0.dtd">
<property-groups>
  <property-group label="Technology" name="okg:technology">
    <select label="Type" name="okp:technology.type" type="multiple">
      <option label="Alfa" value="t1"/>
      <option label="Beta" value="t2" />
      <option label="Omega" value="t3" />
    </select>
    <select label="Language" name="okp:technology.language" type="simple">
      <option label="Java" value="java"/>
      <option label="Python" value="python"/>
      <option label="PHP" value="php" />
    </select>
    <input label="Comment" name="okp:technology.comment"/>
    <textarea label="Description" name="okp:technology.description"/>
    <input label="Link" type="link" name="okp:technology.link"/>
  </property-group>
</property-groups>

Add a metadata group:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X PUT \
  http://localhost:8080/OpenKM/services/rest/propertyGroup/addGroup?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf\&grpName=okg:technology

Set metadata group values:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
  -X PUT -H "Content-Type: application/xml" \
  -d '<simplePropertiesGroup><simplePropertyGroup><name>okp:technology.comment</name><value>RESTful rulez!</value></simplePropertyGroup></simplePropertiesGroup>' \
  http://localhost:8080/OpenKM/services/rest/propertyGroup/setPropertiesSimple?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf\&grpName=okg:technology

Notes samples

Create a note:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   -X POST -H "Content-Type: application/json" -d 'Hello, world!' \
   http://localhost:8080/OpenKM/services/rest/note/add?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf

Conversion samples

With 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/services/rest/conversion/doc2pdf

Or also from a 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/services/rest/conversion/doc2txt

Convert an image file to txt:

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