RESTful

OpenKM dispone de una API completa expuesta mediante REST. Puede llamar a cualquier método de la API desde cualquier lenguaje de programación, como Java, PHP o Python. Esta característica permite crear un cliente personalizado o integrarse con aplicaciones de terceros, como un CRM o un CMS.

Nota

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

Puede ampliar la API REST; encontrará más información en Creación de su propio plugin REST (ampliación de la API REST).

Consejo

Le recomendamos que utilice nuestros SDK para acceder a OpenKM mediante la API REST en lugar de crear su propio cliente; más información:

• El SDK para Java.
• El SDK para .NET.

En la mayoría de los ejemplos verá parámetros llamados “docId”, “fldId” o “nodeId”. El valor de este parámetro puede ser un UUID de nodo válido (desde la versión 7.x, la mayoría de los métodos que aceptan una ruta están obsoletos).

Consejo

Ejemplo de un nodeId:

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

Nota

Casi todos los ejemplos utilizan el comando curl; encontrará más información en el tutorial de curl con ejemplos de uso.

Ejemplo de uso

Puede utilizar una biblioteca de cliente HTTP o cualquier cliente REST para probar estos métodos de la API, lo que facilita el proceso. O bien 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/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 nueva carpeta:

$ 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

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

Para descargarlo:

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

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

$ 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

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

Convertir un fichero doc a PDF:

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

O 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 fichero doc a txt:

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

Convertir un fichero de imagen a txt:

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

Ejemplos del plugin REST

Con el plugin REST puede ampliar la API REST predeterminada.

$ curl -u okmAdmin:admin -G \
    -H "Accept: application/json" \
    --data-urlencode "className=com.openkm.plugin.rest.TestRestPlugin" \
    --data-urlencode 'param={"key":"key1","value":"value1"}' \
    http://localhost:8080/openkm/rest/plugins