Difference between revisions of "RESTful Guide"

From OpenKM Documentation
Jump to: navigation, search
(Sample use)
Line 70: Line 70:
  
 
   $ 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
  
Line 76: Line 76:
  
 
   $ 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/x-www-form-urlencoded" -d '/okm:root/newfolder' \
 
     http://localhost:8080/OpenKM/services/rest/document/createSimple
 
     http://localhost:8080/OpenKM/services/rest/document/createSimple
  
Line 82: Line 82:
  
 
   $ 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/x-www-form-urlencoded" -d 'Hello, world!' \
 
     http://localhost:8080/OpenKM/services/rest/note/add/1b983809-8473-40f1-8e83-ff6b20088c08
 
     http://localhost:8080/OpenKM/services/rest/note/add/1b983809-8473-40f1-8e83-ff6b20088c08
  

Revision as of 11:44, 30 July 2013

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 on OpenKM Professiona 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 use

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/3492d662-b58e-417c-85b6-930ad0c6c3cf

The result is:

{"folderList":
  {"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:

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

The result in XML is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<folderList>
  <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>
</folderList>

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

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 -H "Content-Type: application/x-www-form-urlencoded" -d '/okm:root/newfolder' \
   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):

 $ curl -u okmAdmin:admin -H "Accept: application/json" \
   -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'Hello, world!' \
   http://localhost:8080/OpenKM/services/rest/note/add/1b983809-8473-40f1-8e83-ff6b20088c08

More info at: