REST API

Specification of REST API

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

Supported operations

List of documents in a given folder or the root folder
Get a document
Upload a document into a given folder or the root folder
Create a new revision
Entries operations 5.1 Copy 5.2 Move 5.3 Download 5.4 Delete
Delete a document
Create a folder
List folder content & check folder existence (by folder title)
List folder content & check folder existence (by folder id)
Update a folder
Copy a folder
Move a folder
Delete a folder
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>Prototype</value2>
  ....
</custom_field_values>

The tag format is as follows: <{Whatever_tag_name}{Custom field ID}>. So the tag name must contain ID of the corresponding custom field.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API

Specification of REST API

Supported operations

Description

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

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

2. Get a document

Document details

Document content

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

Upload

Commit

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)

10. Update a folder

11. Copy a folder

12. Move a folder

13. Delete a folder

14. Create a symbolic link

Sample clients

Ruby

CURL

Clone this wiki locally