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.

En casi todos los ejemplos verá parámetros llamados “docId”, “fldId” o “nodeId”. El valor de este parámetro puede ser el UUID de un nodo válido (a partir de la versión 7.x hemos dejado obsoletos casi todos los métodos en los que se puede utilizar la ruta).

Ejemplo de uso

Puede utilizar una biblioteca cliente HTTP o cualquier cliente REST para probar estos métodos de la API, lo que facilita el proceso. O puede utilizar la aplicación de línea de comandos curl. Por ejemplo, puede listar los hijos de una carpeta:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
   http://localhost:8080/openkm/rest/folders/de7b07c2-e707-4390-b5cc-cae340c8c3e5/children

El resultado es:

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

En este caso, puede ver el resultado en formato JSON.

Este es un cliente Java para la misma llamada:

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

Ejemplos de carpetas

Crear una carpeta nueva:

$ 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

Renombrar una carpeta:

$ curl -u okmAdmin:admin -H "Accept: application/json" \
  -X PUT -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'newName=test2' \
 http://localhost:8080/openkm/rest/folders/fe239ae2-4d25-4d87-88b2-924d03b87faa/name

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 content=newDoc.txt -F content=@/home/openkm/doc1.txt \
   http://localhost:8080/openkm/rest/documents/parents/fe239ae2-4d25-4d87-88b2-924d03b87faa

Alternativamente, desde un formulario HTML:

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

Y ahora descárguelo:

$ curl -u okmAdmin:admin \
  http://localhost:8080/openkm/rest/documents/dab830ea-2fa8-439f-837e-de15409d88b9/content

Ejemplos de búsqueda

Búsqueda con parámetros:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/openkm/rest/search?keyword=test&name=doc*&mimeType=application/pdf

Búsqueda con metadatos:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
   http://localhost:8080/openkm/rest/search?keyword=test&property='okp:consulting.name=alfa'

Ejemplos de seguridad

Mostrar los usuarios con permisos:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
  http://localhost:8080/openkm/rest/auth/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/permissions/users

Mostrar los roles con permisos:

$ curl -u okmAdmin:admin -H "Accept: application/json" -X GET \
  http://localhost:8080/openkm/rest/auth/nodes/fe239ae2-4d25-4d87-88b2-924d03b87faa/permissions/roles

Añadir un permiso:

$ 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

Revocar un permiso:

$ 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

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

Añadir un grupo de metadatos:

$ 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

Establecer los valores de un grupo de metadatos:

$ 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

Ejemplos de notas

Crear una nota:

$ 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

Ejemplos de conversión

Utilizando la funcionalidad de conversión de la API de OpenKM, puede convertir, por ejemplo, un documento de Microsoft 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/rest/conversion/doc/pdf

Alternativamente, 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/rest/conversion/doc/txt

Convertir un archivo de imagen a TXT:

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