REST API

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. Create a folder
4. Update a folder
5. Find a folder by its name or id
6. Upload a document into a given folder or the root folder

Description

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

List of documents in a given folder or the root folder

iputs: project id, [folder id]

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)

Response:

<?xml version="1.0" encoding="UTF-8"?>
<dmsf>
  <dmsf_folders total_count="18" type="array">
    <folder>
      <id>8</id>
      <title>General requests on a bug tracking system</title>
    </folder>
    <folder>
      <id>9</id>
      <title>Kontron Development Platform analysis</title>
     </folder>
  </dmsf_folders>
  <dmsf_files total_count="5" type="array">
    <file>
      <id>17190</id>
      <name>cech.pdf</name>
    </file>
    <file>
      <id>17206</id>
      <name>my_account.png</name>
    </file>
  </dmsf_files>
  <dmsf_links total_count="3" type="array">
    <link>
     <id>1</id>
     <name>file_link</name>
     <target_type>DmsfFile</target_type>
     <target_id>123</target_id>
     <target_project_id>12</target_project_id>
    </link>
    <link>
     <id>2</id>
     <name>folder_link</name>
     <target_type>DmsfFolder</target_type>
     <target_id>23</target_id>
     <target_project_id>12</target_project_id>
    </link>
    <link>
     <id>22</id>
     <name></name>
     <target_type>DmsfUrl</target_type>
     <target_id/>
     <target_project_id>12</target_project_id>
     <external_url>https://github.com/danmunn/redmine_dmsf</external_url>
    </link>
  </dmsf_links>
</dmsf>

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_folders total_count="1" type="array">
  <folder>
    <id>2</id>
    <title>folder2</title>
  </folder>
  </dmsf_folders>
  <dmsf_files total_count="0" type="array">
  </dmsf_files>
  <dmsf_links total_count="0" type="array">
  </dmsf_links>
  <found_folder>
    <id>1</id>
    <title>folder1</title>
  </found_folder>
</dmsf>

Get a document

The method return all document details.

iputs: document id

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

Document details

Query:

GET /dmsf/files/17216.xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<file>
  <id>17216</id>
  <name>Rakefile</name>
  <project_id>12</project_id>
  <version>0.1</version>
  <content_url>http://localhost:3000/dmsf/files/17216/download</content_url>
</file>

Document content

Query:

GET /dmsf/files/17216/download

Response:

The file itself as a binary stream

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>

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>

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>
    <disk_filename>cat.gif</disk_filename>
    <name>cat.gif</name>
    <title>cat.gif</title>
    <description>REST API</description>
    <comment>From API</comment>
    <version/>
    <token>15817.c49f68ff81b552d315927df2e27df506</token>
  </uploaded_file>
</attachments>

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>

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

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

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