RESTful

OpenKM tiene una API completa expuesta mediante REST. Esto significa que puede llamar a cualquiera de estos métodos de la API desde cualquier lenguaje de programación, como Java, PHP o Python, entre otros. Esta funcionalidad permite crear un cliente a medida o integrarse con aplicaciones de terceros como un CRM o un CMS.

Nota

Si dirige su navegador a http://localhost:8080/OpenKM/services, podrá ver todos los servicios web disponibles. Al principio verá la API SOAP y al final verá una sección Available RESTful services.

Estas URL están protegidas mediante autenticación BASIC, por lo que debe proporcionar un usuario y una contraseña para acceder a ellas.

Puede ampliar la API REST. Más información en Creating your own Rest Plugin ( extending REST API ).

Consejo

Le recomendamos utilizar nuestros SDK para acceder a OpenKM a través de la API REST en lugar de construir su propio cliente; más información:

• El SDK for Java de SDK for JAVA.
• El SDK for .NET de SDK for .NET.
• El SDK for .NET de SDK for PHP.

En casi todos los ejemplos verá parámetros llamados “docId”, “fldId” o “nodeId”. El valor de este parámetro puede ser un UUID o una ruta de nodo válidos.

Consejo

Ejemplo de nodeId:

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

Nota

Casi todos los ejemplos utilizan el comando curl; más información en curl tutorial with examples of usage.

Ejemplo de uso

Para probar estos métodos de la API puede utilizar una biblioteca de cliente HTTP o cualquier cliente REST que facilite este proceso. O, simplemente, puede utilizar la aplicación de línea de comandos curl. Por ejemplo, puede listar las carpetas hijas:

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

El resultado es:

{"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}
    ]
  }
}

En este caso puede ver el resultado en formato JSON. Si necesita una salida en XML, puede forzarla mediante la cabecera ’Accept:  

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

El resultado en XML es:

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

Este es un cliente Java para la misma llamada:  

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();
        }
    }
}

Ejemplos de carpetas

Crear una carpeta nueva:

$ 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

Ejemplos de documentos

Para crear un documento, debemos proporcionar los datos binarios del documento:

$ 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

O también desde un formulario HTML:

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

Y ahora descárguelo:  

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

Ejemplos de búsqueda

Búsqueda básica por contenido:

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

Búsqueda básica por palabra clave:

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

Búsqueda con parámetros:

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

Búsqueda con metadatos:

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

Ejemplos de seguridad

Mostrar los usuarios con permisos:

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

Mostrar los roles con permisos:

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

Añadir un permiso:

$ 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

Revocar un permiso:

$ 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

Ejemplos de metadatos

La definición del grupo de metadatos utilizada en los ejemplos:

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

Añadir un grupo de metadatos:

$ 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

Establecer los valores de un grupo de metadatos:

$ 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

Ejemplos de notas

Crear una nota:

$ 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

Ejemplos de conversión

Con la funcionalidad de conversión de la API de OpenKM, puede convertir, por ejemplo, un documento en formato MS Office Word a PDF, entre otros tipos de conversión disponibles.

Convertir un archivo doc a pdf:

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

O también desde un formulario HTML:

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

Convertir un archivo doc a txt:

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

Convertir un archivo de imagen a txt:

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