Difference between revisions of "RESTful Guide"

From OpenKM Documentation
Jump to: navigation, search
 
(36 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{TOCright}} __TOC__
 +
 +
{{Note|If you're interested in use OpenKM API we suggest to '''take a look at ours [[SDK]]'s''' and take advantage of already usable libraries which connect to webservices API.}}
 +
 
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 [[Third-party system integration|integrate with third-party applications]] like a CRM or a CMS.
 
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 [[Third-party system integration|integrate with third-party applications]] like a CRM or a CMS.
  
{{Advice|For now this API is only available on OpenKM Professiona 6.4.2. This API is in development, so expect changes.}}
+
{{Advice|For now this API is only available since OpenKM Professional 6.2.20 and 6.4.2. This API is in development, so expect changes.}}
  
 
If you point your browser to http://localhost:8080/OpenKM/services, you can see the SOAP API at first place but 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.
 
If you point your browser to http://localhost:8080/OpenKM/services, you can see the SOAP API at first place but 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.
  
== Sample use ==
+
== 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:
 
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" \
+
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
    http://localhost:8080/OpenKM/services/rest/folder/getChildren/3492d662-b58e-417c-85b6-930ad0c6c3cf
+
    http://localhost:8080/OpenKM/services/rest/folder/getChildren?fldId=3492d662-b58e-417c-85b6-930ad0c6c3cf
  
 
The result is:
 
The result is:
  
 
<source lang="text">
 
<source lang="text">
{"folderList":
+
{"folders":
 
   {"folder":
 
   {"folder":
 
     [
 
     [
Line 38: Line 42:
 
In this case you can see the result in JSON format. Otherwise you can need an XML output, which can be forced using the '''Accept'' header:
 
In this case you can see the result in JSON format. Otherwise you can need an XML output, which can be forced using the '''Accept'' header:
  
   $ url -u okmAdmin:admin -H "Accept: application/xml" \
+
   $ curl -u okmAdmin:admin -H "Accept: application/xml" \
     http://localhost:8080/OpenKM/services/rest/folder/getChildren/3492d662-b58e-417c-85b6-930ad0c6c3cf
+
     http://localhost:8080/OpenKM/services/rest/folder/getChildren?fldId=3492d662-b58e-417c-85b6-930ad0c6c3cf
  
 
The result in XML is:
 
The result in XML is:
Line 45: Line 49:
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<folderList>
+
<folders>
 
   <folder>
 
   <folder>
 
     <author>okmAdmin</author>
 
     <author>okmAdmin</author>
Line 64: Line 68:
 
     <hasChildren>false</hasChildren>
 
     <hasChildren>false</hasChildren>
 
   </folder>
 
   </folder>
</folderList>
+
</folders>
 +
</source>
 +
 
 +
This is a Java client for the same call:
 +
 
 +
<source lang="java">
 +
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();
 +
        }
 +
    }
 +
}
 
</source>
 
</source>
  
 +
== Folder ==
 
Let's create a new folder:
 
Let's create a new folder:
  
 
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
 
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
     -X PUT -H "Content-Type: application/json" -d '/okm:root/newfolder' \
+
     -X POST -H "Content-Type: application/json" -d '/okm:root/newfolder' \
 
     http://localhost:8080/OpenKM/services/rest/folder/createSimple
 
     http://localhost:8080/OpenKM/services/rest/folder/createSimple
  
 +
== Document ==
 
Now we are going to create a document. For this, we need to provide the document binary data:
 
Now we are going to create a document. For this, we need to provide the document binary data:
  
 
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
 
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
     -X PUT -H "Content-Type: application/json" -d '/okm:root/newfolder' \
+
     -X POST -F docPath=/okm:root/newDoc.txt -F content=@newDoc.txt \
 
     http://localhost:8080/OpenKM/services/rest/document/createSimple
 
     http://localhost:8080/OpenKM/services/rest/document/createSimple
  
To create a note in a OpenKM folder or document you can do this (previously you need to know the node UUID, in this case is ''1b983809-8473-40f1-8e83-ff6b20088c08''):
+
Or also from a HTML form:
 +
 
 +
<source lang="html4strict">
 +
<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>
 +
</source>
 +
 
 +
And now download it:
 +
 
 +
  $ curl -u okmAdmin:admin \
 +
    http://localhost:8080/OpenKM/services/rest/document/getContent?docId=58f79fa6-fe6e-4f68-8517-68a60898d122
 +
 
 +
== Search ==
 +
Search simply by content:
 +
 
 +
  $ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
 +
    http://localhost:8080/OpenKM/services/rest/search/findByContent?content=santo+grial
 +
 
 +
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
 +
 
 +
Or use a more customized search parameters:
 +
 
 +
  $ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
 +
    http://localhost:8080/OpenKM/services/rest/search/find?content=grial\&mimeType=application/pdf
 +
 
 +
Even can query by Property Groups:
 +
 
 +
  $ 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 ==
 +
Let's see the security info associated to a given node. First 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
 +
 
 +
And now the 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
 +
 
 +
To grant some permissions do:
 +
 
 +
  $ 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
 +
 
 +
And revoke using:
 +
 
 +
  $ 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
 +
 
 +
== Property Groups ==
 +
In this example we add a property 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
 +
 
 +
And set some property 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 ==
 +
To create a note in a OpenKM folder or document you can do this (previously you need to know the node UUID):
  
 
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
 
   $ curl -u okmAdmin:admin -H "Accept: application/json" \
     -X PUT -H "Content-Type: application/json" -d 'Hello, world!' \
+
     -X POST -H "Content-Type: application/json" -d 'Hello, world!' \
     http://localhost:8080/OpenKM/services/rest/note/add/1b983809-8473-40f1-8e83-ff6b20088c08
+
     http://localhost:8080/OpenKM/services/rest/note/add?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf
 +
 
 +
== Conversion ==
 +
Since OpenKM Professional 6.4.10 you can access the document format conversion feature from this API. For example you can convert a document from MS Office Word format to PDF:
 +
 
 +
Now we are going to create a document. For this, we need to provide the document binary data:
 +
 
 +
  $ 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:
 +
 
 +
<source lang="html4strict">
 +
<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>
 +
</source>
 +
 
 +
In this sample we use this API to extract text from a document:
 +
 
 +
  $ curl -u okmAdmin:admin -F content=@sample.doc http://localhost:8080/OpenKM/services/rest/conversion/doc2txt
 +
 
 +
You can also make use of the integrated OCR engine. For example:
 +
 
 +
  $ curl -u okmAdmin:admin -F content=@sample.tif http://localhost:8080/OpenKM/services/rest/conversion/img2txt
  
 
More info at:
 
More info at:

Latest revision as of 16:56, 26 November 2014


Nota clasica.png If you're interested in use OpenKM API we suggest to take a look at ours SDK's and take advantage of already usable libraries which connect to webservices API.

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.


Nota idea.png For now this API is only available since OpenKM Professional 6.2.20 and 6.4.2. This API is in development, so expect changes.

If you point your browser to http://localhost:8080/OpenKM/services, you can see the SOAP API at first place but 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.

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

Let's 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

Now we are going to create a document. For this, 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

Search simply by content:

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

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

Or use a more customized search parameters:

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

Even can query by Property Groups:

 $ 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

Let's see the security info associated to a given node. First 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

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

To grant some permissions do:

 $ 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

And revoke using:

 $ 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

Property Groups

In this example we add a property 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

And set some property 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

To create a note in a OpenKM folder or document you can do this (previously you need to know the node UUID):

 $ 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

Since OpenKM Professional 6.4.10 you can access the document format conversion feature from this API. For example you can convert a document from MS Office Word format to PDF:

Now we are going to create a document. For this, we need to provide the document binary data:

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

In this sample we use this API to extract text from a document:

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

You can also make use of the integrated OCR engine. For example:

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

More info at: