Difference between revisions of "RESTful Guide with curl"

From LogicalDOC Community Wiki
Jump to navigationJump to search
(Folder)
m (Search)
(30 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
{{Note|If you're interested in use LogicalDOC API we suggest to '''take a look at ours [[Bindings_And_Samples|Bindings and Samples]] and take advantage of already usable examples which connect to webservices API.}}
 
{{Note|If you're interested in use LogicalDOC API we suggest to '''take a look at ours [[Bindings_And_Samples|Bindings and Samples]] and take advantage of already usable examples which connect to webservices API.}}
  
LogicalDOC 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.
+
LogicalDOC has a [http://docs.logicaldoc.com/en/web-services-api 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.
  
{{Advice|This API is only available since LogicalDOC 7.5 and is currently in development, so expect changes and additions.}}
+
{{Advice|Examples in this page refer to LogicalDOC 7.7; the [http://docs.logicaldoc.com/en/web-services-api REST API] is currently in development, so expect changes and additions.}}
  
If you point your browser to http://localhost:8080/logicaldoc/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/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 ==
 
== Sample usage ==
Line 13: Line 13:
  
 
   $ curl -u admin:admin -H "Accept: application/json" \
 
   $ curl -u admin:admin -H "Accept: application/json" \
     http://localhost:8080/logicaldoc/services/rest/folder/listChildren?folderId=4
+
     http://localhost:8080/services/rest/folder/listChildren?folderId=4
  
 
The result is:
 
The result is:
Line 62: Line 62:
  
 
   $ curl -u admin:admin -H "Accept: application/xml" \
 
   $ curl -u admin:admin -H "Accept: application/xml" \
     http://localhost:8080/logicaldoc/services/rest/folder/listChildren?folderId=4
+
     http://localhost:8080/services/rest/folder/listChildren?folderId=4
  
 
The result in XML is:
 
The result in XML is:
Line 114: Line 114:
 
         try {
 
         try {
 
             long folderID = 4L;
 
             long folderID = 4L;
             URL url = new URL("http://localhost:8080/logicaldoc/services/rest/folder/listChildren?folderId=" + folderID);
+
             URL url = new URL("http://localhost:8080/services/rest/folder/listChildren?folderId=" + folderID);
 
             HttpURLConnection conn = (HttpURLConnection) url.openConnection();
 
             HttpURLConnection conn = (HttpURLConnection) url.openConnection();
 
             conn.setRequestMethod("GET");
 
             conn.setRequestMethod("GET");
Line 152: Line 152:
 
   $ curl -u admin:admin -H "Accept: application/json" \
 
   $ curl -u admin:admin -H "Accept: application/json" \
 
     -X POST -H "Content-Type: text/plain" -d "/Default/Curl/newfolder" \
 
     -X POST -H "Content-Type: text/plain" -d "/Default/Curl/newfolder" \
     http://localhost:8080/logicaldoc/services/rest/folder/createSimple
+
     http://localhost:8080/services/rest/folder/createSimple
 +
 
 +
Creates a path of folders starting from the folder with ID 4 (Default folder)
 +
 
 +
  $ curl -u admin:admin -H "Accept: application/json" \
 +
    -X POST -H "Content-Type: application/x-www-form-urlencoded" -d parentId=4 -d path=How/to/POST/JSON/data/with/Curl \
 +
    http://localhost:8080/services/rest/folder/createPath
  
 
== Document ==
 
== Document ==
Line 158: Line 164:
  
 
   $ curl -u admin:admin -H "Accept: application/json" \
 
   $ curl -u admin:admin -H "Accept: application/json" \
     -X POST -F docPath=/Default/newDoc.txt -F content=@newDoc.txt \
+
     -X POST -F folderId=4 -F filename=CHANGELOG.txt -F filedata=@CHANGELOG.txt \
     http://localhost:8080/logicaldoc/services/rest/document/createSimple
+
     http://localhost:8080/services/rest/document/upload
 +
 
 +
In this case the document will be added to the respository using the default language (english). Of course it is possible to specify the additional parameter 'language' to tell the system that the document we are storing is in german (ISO 639-2 code)
 +
 
 +
  $ curl -u admin:admin -H "Accept: application/json" \
 +
    -X POST -F folderId=4 -F filename=pub_arbeitsplatz_straße.pdf -F language=de -F filedata=@pub_arbeitsplatz_straße.pdf \
 +
    http://localhost:8080/services/rest/document/upload
 +
 
  
 
Or also from a HTML form:
 
Or also from a HTML form:
Line 167: Line 180:
 
   <body>
 
   <body>
 
     <form method="POST" enctype="multipart/form-data"
 
     <form method="POST" enctype="multipart/form-data"
           action="http://localhost:8080/logicaldoc/services/rest/document/createSimple">
+
           action="http://localhost:8080/services/rest/document/upload">
       Select file: <input type="file" name="content" size="45"/><br/>
+
       Select folder: <input type="text" name="folderId" value="4"/><br/>
       Select path: <input type="text" name="docPath" value="/Default/newDoc.txt"/><br/>
+
       Select filename: <input type="text" name="filename" /><br/>
 +
      Select file: <input type="file" name="filedata" size="45"/><br/>
 
       <input type="submit" value="Upload" />
 
       <input type="submit" value="Upload" />
 
     </form>
 
     </form>
Line 179: Line 193:
  
 
   $ curl -u admin:admin \
 
   $ curl -u admin:admin \
     http://localhost:8080/logicaldoc/services/rest/document/getContent?docId=58f79fa6-fe6e-4f68-8517-68a60898d122
+
     http://localhost:8080/services/rest/document/getContent?docId=456456456
  
== Search ==
+
If the document is a binary file you can redirect the output to a file adding '> filename' to the end of the command
Search simply by content:
 
  
   $ curl -u admin:admin -H "Accept: application/json" -X GET \
+
   $ curl -u admin:admin \
     http://localhost:8080/logicaldoc/services/rest/search/findByContent?content=santo+grial
+
     http://localhost:8080/services/rest/document/getContent?docId=456456456 > myFile.pdf
  
Search by keyword:
+
Delete a specific version of a given document (since v7.6.4)
  
   $ curl -u admin:admin -H "Accept: application/json" -X GET \
+
   $ curl -u admin:admin \
    http://localhost:8080/logicaldoc/services/rest/search/findByKeywords?keyword=santo\&keyword=grial
+
    -G -d docId=1803 -d version=1.3 -X DELETE http://localhost:8080/services/rest/document/deleteVersion
  
Or use a more customized search parameters:
+
Update the document metadata. Specifically, we can see how to update an extended attribute field of type date (type = 3) using the property dateValue
  
   $ curl -u admin:admin -H "Accept: application/json" -X GET \
+
   $ curl -v -u admin:admin -H "Content-Type: application/json" -H "Accept: application/json" -X PUT \
     http://localhost:8080/logicaldoc/services/rest/search/find?content=grial\&mimeType=application/pdf
+
    -d "{ \"id\": 47, \"folderId\": 4, \"fileName\":\"Egzai_u002.doc\", \"templateId\":92241920, \"attributes\":[{\"name\":\"ack\",\"stringValue\":\"ack\",\"type\":0},{\"name\":\"Tar\",\"dateValue\":\"2017-03-18 19:10:00 +0100\",\"type\":3}] }" \  
 +
     http://localhost:8080/services/rest/document/update
  
Even can query by Property Groups:
+
== Search ==
 
+
Standard Full-text search on content, title and tags using english as language of the query (expressionLanguage) and on english documents (language):
  $ curl -u admin:admin -H "Accept: application/json" -X GET \
 
    http://localhost:8080/logicaldoc/services/rest/search/find?content=grial\&property='okp:name=alfa'
 
 
 
 
 
== Notes ==
 
To create a note in a LogicalDOC folder or document you can do this (previously you need to know the node UUID):
 
 
 
  $ curl -u admin:admin -H "Accept: application/json" \
 
    -X POST -H "Content-Type: application/json" -d 'Hello, world!' \
 
    http://localhost:8080/logicaldoc/services/rest/note/add?nodeId=3492d662-b58e-417c-85b6-930ad0c6c3cf
 
  
 +
  $ curl -u admin:admin -H "Content-Type: application/json" -H "Accept: application/json" -X POST \
 +
    -d "{\"maxHits\":50,\"expression\":\"document management system\",\"expressionLanguage\":\"en\",\"language\":\"en\"}"
 +
    http://localhost:8080/services/rest/search/find
  
 
More info at:
 
More info at:
  
 
* [http://www.yilmazhuseyin.com/blog/dev/curl-tutorial-examples-usage/ curl tutorial with examples of usage]
 
* [http://www.yilmazhuseyin.com/blog/dev/curl-tutorial-examples-usage/ curl tutorial with examples of usage]
 +
* [http://docs.logicaldoc.com/resources/wsdoc/rest/index.html?version=7.6.4 LogicalDOC REST API reference v7.6.4]
 +
* [https://docs.logicaldoc.com/resources/wsdoc/rest/index.html?version=7.7.6 LogicalDOC REST API reference v7.7.6]
 +
* [https://docs.logicaldoc.com/resources/wsdoc/rest/index.html?version=8.1.0 LogicalDOC REST API reference v8.1]
 +
* [[Bindings_And_Samples|Webservices - Binding and Examples]]
 +
* [https://docs.logicaldoc.com/en/web-services-api LogicalDOC Web Services API]
 +
 
[[Category: RESTful Guide]]
 
[[Category: RESTful Guide]]

Revision as of 08:42, 31 January 2019


Classic note.png If you're interested in use LogicalDOC API we suggest to take a look at ours Bindings and Samples and take advantage of already usable examples which connect to webservices API.


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


Note idea.png Examples in this page refer to LogicalDOC 7.7; the REST API is currently in development, so expect changes and additions.


If you point your browser to http://localhost:8080/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 admin:admin -H "Accept: application/json" \
   http://localhost:8080/services/rest/folder/listChildren?folderId=4

The result is:

[
  {
    "id": 3440640,
    "name": "alfa",
    "parentId": 4,
    "description": "",
    "lastModified": "2016-06-15 15:49:40 +0200",
    "type": 0,
    "templateId": null,
    "templateLocked": 0,
    "creation": "2016-06-15 15:49:40 +0200",
    "creator": "Admin Admin",
    "position": 1,
    "hidden": 0,
    "foldRef": null,
    "attributes": [
      
    ]
  },
  {
    "id": 3440643,
    "name": "beta",
    "parentId": 4,
    "description": "",
    "lastModified": "2016-06-16 10:16:25 +0200",
    "type": 0,
    "templateId": null,
    "templateLocked": 0,
    "creation": "2016-06-16 09:49:27 +0200",
    "creator": "Admin Admin",
    "position": 1,
    "hidden": 0,
    "foldRef": null,
    "attributes": [
      
    ]
  }
]

In this case you can see the result in JSON format. Some endpoints can also provide the results in XML format but you have to check them, if that is supported we can make a call sending the appropriate Accept header:

 $ curl -u admin:admin -H "Accept: application/xml" \
   http://localhost:8080/services/rest/folder/listChildren?folderId=4

The result in XML is:

<?xml version="1.0" encoding="UTF-8"?>
<folders>
  <folder>
    <creation>2016-06-15 15:49:40 +0200</creation>
    <creator>Admin Admin</creator>
    <description></description>
    <hidden>0</hidden>
    <id>3440640</id>
    <lastModified>2016-06-15 15:49:40 +0200</lastModified>
    <name>alfa</name>
    <parentId>4</parentId>
    <position>1</position>
    <templateLocked>0</templateLocked>
    <type>0</type>
  </folder>
  <folder>
    <creation>2016-06-16 09:49:27 +0200</creation>
    <creator>Admin Admin</creator>
    <description></description>
    <hidden>0</hidden>
    <id>3440643</id>
    <lastModified>2016-06-16 10:16:25 +0200</lastModified>
    <name>beta</name>
    <parentId>4</parentId>
    <position>1</position>
    <templateLocked>0</templateLocked>
    <type>0</type>
  </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 {
            long folderID = 4L;
            URL url = new URL("http://localhost:8080/services/rest/folder/listChildren?folderId=" + folderID);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");
            
            Authenticator.setDefault(new Authenticator() {
                protected PasswordAuthentication getPasswordAuthentication() {
                    return new PasswordAuthentication("admin", "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 admin:admin -H "Accept: application/json" \
   -X POST -H "Content-Type: text/plain" -d "/Default/Curl/newfolder" \
   http://localhost:8080/services/rest/folder/createSimple

Creates a path of folders starting from the folder with ID 4 (Default folder)

 $ curl -u admin:admin -H "Accept: application/json" \
   -X POST -H "Content-Type: application/x-www-form-urlencoded" -d parentId=4 -d path=How/to/POST/JSON/data/with/Curl \
   http://localhost:8080/services/rest/folder/createPath

Document

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

 $ curl -u admin:admin -H "Accept: application/json" \
   -X POST -F folderId=4 -F filename=CHANGELOG.txt -F filedata=@CHANGELOG.txt \
   http://localhost:8080/services/rest/document/upload

In this case the document will be added to the respository using the default language (english). Of course it is possible to specify the additional parameter 'language' to tell the system that the document we are storing is in german (ISO 639-2 code)

 $ curl -u admin:admin -H "Accept: application/json" \
   -X POST -F folderId=4 -F filename=pub_arbeitsplatz_straße.pdf -F language=de -F filedata=@pub_arbeitsplatz_straße.pdf \
   http://localhost:8080/services/rest/document/upload


Or also from a HTML form:

<html>
  <body>
    <form method="POST" enctype="multipart/form-data"
          action="http://localhost:8080/services/rest/document/upload">
      Select folder: <input type="text" name="folderId" value="4"/><br/>
      Select filename: <input type="text" name="filename" /><br/>
      Select file: <input type="file" name="filedata" size="45"/><br/>
      <input type="submit" value="Upload" />
    </form>
  </body>
</html>

And now download it:

 $ curl -u admin:admin \
   http://localhost:8080/services/rest/document/getContent?docId=456456456

If the document is a binary file you can redirect the output to a file adding '> filename' to the end of the command

 $ curl -u admin:admin \
   http://localhost:8080/services/rest/document/getContent?docId=456456456 > myFile.pdf

Delete a specific version of a given document (since v7.6.4)

 $ curl -u admin:admin \
   -G -d docId=1803 -d version=1.3 -X DELETE http://localhost:8080/services/rest/document/deleteVersion

Update the document metadata. Specifically, we can see how to update an extended attribute field of type date (type = 3) using the property dateValue

 $ curl -v -u admin:admin -H "Content-Type: application/json" -H "Accept: application/json" -X PUT \
   -d "{ \"id\": 47, \"folderId\": 4, \"fileName\":\"Egzai_u002.doc\", \"templateId\":92241920, \"attributes\":[{\"name\":\"ack\",\"stringValue\":\"ack\",\"type\":0},{\"name\":\"Tar\",\"dateValue\":\"2017-03-18 19:10:00 +0100\",\"type\":3}] }" \ 
   http://localhost:8080/services/rest/document/update

Search

Standard Full-text search on content, title and tags using english as language of the query (expressionLanguage) and on english documents (language):

 $ curl -u admin:admin -H "Content-Type: application/json" -H "Accept: application/json" -X POST \
   -d "{\"maxHits\":50,\"expression\":\"document management system\",\"expressionLanguage\":\"en\",\"language\":\"en\"}" 
   http://localhost:8080/services/rest/search/find

More info at: