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.

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 ).

We encourage using our SDK's for accessing OpenKM across REST API rather than you build your own client, more information:

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 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 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/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

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 a 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 2.0//EN"
                                 "http://www.openkm.com/dtd/property-groups-2.0.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 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 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/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