Skip to content

REST API

Jump to bottom
Karel Pičman edited this page Sep 11, 2023 · 68 revisions

Specification of REST API

DMSF REST API is an interface to access DMSF data from other aplications.

Supported operations

  1. List of documents in a given folder or the root folder
  2. Get a document
  3. Upload a document into a given folder or the root folder
  4. Create a new revision
  5. Entries operations 5.1 Copy 5.2 Move 5.3 Download 5.4 Delete
  6. Delete a document
  7. Create a folder
  8. List folder content & check folder existence (by folder title)
  9. List folder content & check folder existence (by folder id)
  10. Update a folder
  11. Copy a folder
  12. Move a folder
  13. Delete a folder
  14. Create a symbolic link

Description

BOTH XML and JSON formats are supported. Just replace .xml with .json.

1. List of documents in a given folder or the root folder

iputs: project id, [folder id], [offset], [limit]

outputs: list of sub-folders, files and links

Query:

GET /projects/12/dmsf.xml (the root folder)

GET /projects/12/dmsf.xml?folder_id=51 (a sub-folder)

GET /projects/12/dmsf.xml?offset=25&limit=25 (offset and limit)

Response:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf>
  <dmsf_nodes total_count="5" type="array">
    <node>
      <id>8</id>
      <title>General requests on a bug tracking system</title>
      <type>folder</type>
    </node>
    <node>
      <id>17190</id>
      <title>Cech</title>
      <type>file</type>
      <filename>cech.pdf</filename>
    </node>
    <node>
     <id>1</id>
     <title>File link</title>
     <type>file-link</type>
     <target_id>123</target_id>
     <target_project_id>12</target_project_id>
    </node>
    <node>
     <id>2</id>
     <title>Folder link</title>
     <type>folder-link</type>
     <target_id>23</target_id>
     <target_project_id>12</target_project_id>
    </node>
    <node>
     <id>22</id>
     <title>URL link</title>
     <type>url-link</type>
     <filename>https://github.com/danmunn/redmine_dmsf</filename>
    </node>
  </dmsf_nodes>
</dmsf>

1.1 List of documents in a folder found by name or id

iputs: [folder id, folder name]

outputs: list of sub-folders, files and links, found folder

Query:

GET //projects/12/dmsf.xml?folder_title=folder1 (by folder name)

GET //projects/12/dmsf.xml?folder_id=1 (by folder_id)

Response:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf>
  <dmsf_nodes total_count="2" type="array">
  <node>
    <id>2</id>
    <title>folder2</title>
    <type>dmsf-folder</type>
  </node>
  <node>
    <id>1</id>
    <title>folder1</title>
    <type>dmsf-folder</type>
  </node>
</dmsf>

2. Get a document

The method return all document details.

iputs: document id

outputs: document's properties(id, name, project_id, dmsf_folder_id, version, mime_type, digest, size, description) and download URL(content_url)

Document details

Query:

GET /dmsf/files/17216.xml

Response:

 <?xml version="1.0" encoding="UTF-8"?>
 <dmsf_file>
   <id>1</id>
   <title>Test File</title>
   <name>test.txt</name>
   <project_id>1</project_id>
   <content_url>http://www.example.com/dmsf/files/1/download</content_url>
   <dmsf_file_revisions type="array">        
     <dmsf_file_revision>
     <id>1</id>
     <source_dmsf_file_revision_id/>
     <name>test.txt</name>
     <content_url>http://www.example.com/dmsf/files/1/view?download=1</content_url>
     <size>4</size>
     <mime_type>text/plain</mime_type>
     <title>Test File</title>
     <description>Some file :-)</description>
     <workflow>1</workflow>
     <version>1.0</version>
     <comment/>
     <user_id>1</user_id>
     <created_at>2017-04-18T12:52:27Z</created_at>
     <updated_at>2019-01-15T15:56:15Z</updated_at>
     <dmsf_workflow_id/>
     <dmsf_workflow_assigned_by>1</dmsf_workflow_assigned_by>
     <dmsf_workflow_assigned_at/>
     <dmsf_workflow_started_by>1</dmsf_workflow_started_by>
     <dmsf_workflow_started_at/>
     <digest>81dc9bdb52d04dc20036dbd8313ed055</digest>
   </dmsf_file_revision>
 </dmsf_file_revisions>
</dmsf_file>

Document content

Query:

GET /dmsf/files/17216/download

Response:

The file itself as a binary stream

3. Upload a document into a given folder or the root folder

Upload

iputs: project id, file name and file

outputs: file token

Query:

POST --data-binary "@cat.gif" //projects/12/dmsf/upload.xml?filename=cat.gif

Content-Type: application/octet-stream
...
(request body is the file content)

Response:

<?xml version="1.0" encoding="UTF-8"?>
<upload>
  <token>15817.c49f68ff81b552d315927df2e27df506</token>
</upload>

Commit

iputs: token, file name, comment, description, [version], [folder_id]

outputs: file id or validation errors if any

Query:

POST --data "@file.xml" //projects/12/dmsf/commit.xml

<?xml version="1.0" encoding="utf-8" ?>
<attachments>
  <folder_id>6118</folder_id>
  <uploaded_file>
    <name>cat.gif</name>
    <title>cat</title>
    <!-- Optional -->
    <description>REST API</description>
    <comment>From API</comment>
    <version_major>A</version_major>
    <version_minor>1</version_minor>
    <version_patch>0</version_patch>
    <!-- End of optional -->
    <token>15838.c49f68ff81b552d315927df2e27df506</token>
  </uploaded_file>
</attachments>

In order to write custom fields, user the following syntax:

<custom_field_values>
  <value1>Design</value1>
  <value2>Design</value2>
  ....
</custom_field_values>

The custom values are assigned in the order writen in XML. So you can omit e.g. the first custom field and write only the second one. In such case try this:

<custom_field_values>
  <value1></value1>
  <value2>Design</value2>
   ....
</custom_field_values>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf_files total_count="1" type="array">
  <file>
    <id>17229</id>
    <name>cat.gif</name>
  </file>
</dmsf_files>

4. Create a new revision

iputs: file id and revision

outputs: revision id

POST --data "@revision.xml" //dmsf/files//123/revision/create.xml

revision.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_file_revision>
	<title>test</title>
	<name>test.sql</name>
	<description>SQL script</description>
	<comment>REST API</comment>
	<custom_field_values>
		<custom_field_value1>Validation</custom_field_value1>
	</custom_field_values>
</dmsf_file_revision>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf_file_revision>
  <id>293566</id>
</dmsf_file_revision>

You can create a new revision of an existing document by uploading a file with the same filename too.

5. Entries operations

5.1 Copy

iputs: file/folders ids of entries to copy, target project and target folder

POST --data "@entries.xml" //dmsf/projects/1/dmsf//entries.xml?ids[]=file-254566&copy_entries=true"

entries.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_entries>
  <target_project_id>3342</target_project_id>
  <target_folder_id>58659</target_folder_id>
</dmsf_entries>

5.2 Move

iputs: file/folders ids of entries to move, target project and target folder

POST --data "@entries.xml" //dmsf/projects/1/dmsf//entries.xml?ids[]=file-254566&move_entries=true"

entries.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_entries>
  <target_project_id>3342</target_project_id>
  <target_folder_id>58659</target_folder_id>
</dmsf_entries>

5.3 Download

iputs: file/folders ids

POST --data "" //dmsf/projects/1/dmsf//entries.xml?ids[]=file-254566"

5.4 Delete

iputs: file/folders ids

POST --data "" //dmsf/projects/1/dmsf//entries.xml?ids[]=file-254566&delete_entries=true"

6. Delete a document

iputs: file id, [commit]

outputs:

Query:

DELETE //dmsf/files/196118.xml?commit=yes

7. Create a folder

iputs: project id, parent folder id, name

outputs: folder id or validation errors if any

Query:

POST --data "@folder.xml" //projects/12/dmsf/create.xml

folder.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_folder>
  <title>rest_api</title>
  <description>A folder created via REST API</description>
  <dmsf_folder_id/>
  <system/>
</dmsf_folder>

Result:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf_folder>
  <id>8</id>
  <title>rest_api</title>
</dmsf_folder>

8. List folder content & check folder existence (by folder title)

iputs: project id, parent folder id, folder title

outputs: folder id or 404 - Not Found

Query:

GET //projects/12/dmsf?folder_title=Title

Result:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf>
  <found_folder>
    <id>8</id>
    <title>Title</title>
  <found_folder>
</dmsf>

### 9. List folder content & check folder existence (by folder id)
**iputs**: project id, parent folder id, folder id

**outputs**: folder id or 404 - Not Found

Query:

`GET //projects/12/dmsf?folder_id=8`

Result:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<dmsf>
  <found_folder>
    <id>8</id>
    <title>Title</title>
  <found_folder>
</dmsf>

10. Update a folder

iputs: project id, folder id, parametrs to change

outputs: folder id or validation errors if any

Query:

POST --data "@folder.xml" //projects/12/dmsf/save.xml?folder_id=1

folder.xml

 <?xml version="1.0" encoding="utf-8" ?>
   <dmsf_folder>
     <title>rest_api</title>
     <description>A folder updated via REST API</description>
   </dmsf_folder>

Result:

 <?xml version="1.0" encoding="UTF-8"?>
   <dmsf_folder>
     <id>1</id>
     <title>rest_api</title>
     <description>A folder updated via REST API</description>
   </dmsf_folder>

11. Copy a folder

iputs: folder id

POST --data "@file_or_folder.xml" //dmsf/folders//123/copy/copy.xml

file_or_folder.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_file_or_folder>
	<target_project_id>1</target_project_id>
	<target_folder_id>1</target_folder_id>
</dmsf_file_or_folder>

12. Move a folder

iputs: folder id

POST --data "@file_or_folder.xml" //dmsf/folders//123/copy/move.xml

file_or_folder.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_file_or_folder>
	<target_project_id>1</target_project_id>
	<target_folder_id>1</target_folder_id>
</dmsf_file_or_folder>

13. Delete a folder

iputs: project id, folder id, [commit]

outputs:

Query:

DELETE //projects/2387/dmsf/delete.xml?folder_id=13&commit=yes

14. Create a symbolic link

iputs: project_id, type, [dmsf_file_id], target_project_id, target_folder_id, target_file_id, [external_url] test </dmsf_link>

outputs: link's id and title or validation errors if any

Query:

POST --data "@link.xml" //projects/dmsf_links.xml

link.xml

<?xml version="1.0" encoding="utf-8" ?>
<dmsf_link>
  <project_id>2387</project_id>
  <dmsf_folder_id/>
  <type>link_from</type>
  <target_project_id>2387</target_project_id>
  <target_folder_id/>
  <target_file_id>196119</target_file_id>
  <external_url></external_url>
  <name>REST API link</name>
</dmsf_link>

Result:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf_link>
  <id>1243</id>
  <title>test</title>
</dmsf_link>

Sample clients

Ruby

require 'rubygems'
require 'active_resource'

# Simple REST API client in Ruby
# usage: ruby api_client.rb [login] [password]

# Dmsf file
class DmsfFile < ActiveResource::Base
  self.site = 'http://localhost:3000/'
  self.user = ARGV[0]
  self.password = ARGV[1]
end

# 3. Get a document
FILE_ID = 17216
file = DmsfFile.find FILE_ID
if file
  puts file.id
  puts file.name
  puts file.version  
  puts file.project_id  
  puts file.content_url
else
  puts "No file with id = #{FILE_ID} found"
end

CURL

# 3. Get a document
curl -v -H "Content-Type: application/xml" -X GET -u ${1}:${2} http://localhost:3000/dmsf/files/17216.xml

Table Of Contents

History of DMSF

Features and screenshots

Migrating from Documents to DMSF

Usage / In-Depth Documentation

Specification

Xapian tools and bindings

Clone this wiki locally