Skip to content

REST API

Jump to bottom
Karel Picman edited this page Jun 11, 2021 · 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. Find a folder by its name or id
  3. Get a document
  4. Create a folder
  5. Update a folder
  6. Upload a document into a given folder or the root folder
  7. Create a revision
  8. Delete a folder
  9. Delete a document
  10. Create a 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>

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

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

4. 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/>
</dmsf_folder>

Result:

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

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

6. 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/>
  <uploaded_file>
    <name>cat.gif</name>
    <title>cat.gif</title>
    <description>REST API</description>
    <comment>From API</comment>
    <!-- For an automatic version: -->
    <version/>
    <!-- or for a custom version: -->
    <version>3</version> <!-- It must be 3 (Custom version) -->
    <custom_version_major>2</custom_version_major> <!-- Major version -->
    <custom_version_minor>4</custom_version_minor> <!-- Minor version -->   
    <!-- End of version -->
    <token>15817.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>

7. Create a 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>

8. Delete a folder

iputs: project id, folder id, [commit]

outputs:

Query:

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

9. Delete a document

iputs: file id, [commit]

outputs:

Query:

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

10. Create a 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>
  <type>link_from</type>
  <dmsf_file_id></dmsf_file_id>
  <target_project_id>2387</target_project_id>
  <target_folder_id>Documents</target_folder_id>
  <target_file_id>196119</target_file_id>
  <external_url></external_url>
  <name>test</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