Skip to content

REST API

Jump to bottom
Karel Picman edited this page Dec 4, 2018 · 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. Delete a folder
  8. Delete a document
  9. 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_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>

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_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>

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"?>
<file>
  <id>17216</id>
  <title>Rakefile</title>
  <name>Rakefile</name>
  <project_id>12</project_id>
  <version>0.1</version>
  <digest>b6a8aca6b9ea2bc0e27add05286379aa</digest>
  <mime_type>text/plain</mime_type>
  <size>4096</size>
  <description>This is my test file</description>
  <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

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>

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. Delete a folder

iputs: project id, folder id, [commit]

outputs:

Query:

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

8. Delete a document

iputs: file id, [commit]

outputs:

Query:

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

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