REST API for Documents

Base URL for all REST calls for documents is /intranet/rest/documents/

Folder read operations

These operations are done using the GET request method.

Standard http error codes can be returned:

• 400 Bad Request
• 404 Not Found
• 403 Forbidden
• 501 Not Implemented

Get folder info

GET /intranet/rest/documents/folder/:id/info

Doesn't have any other parameters.

Returns JSON-formatted folder data for folder with :id in the following format:

{
    'id': 15,
    'parent_id': 0,
    'obj_type': 'folder',
    'type': 'folder',
    'title': "Import from fs 2",
    'refcode': "Dir_15",
    'description': "~500 files inside",
    'date_created': {
        'date_str': "06-04-2011 17:16 NOVST",
        'timezone': "Asia/Novosibirsk",
        'date': "20110406101600"
      },
    'date_last_modified': {
        'date_str': "29-08-2011 13:43 NOVST",
        'timezone': "Asia/Novosibirsk",
        'date': "20110829064336"
      },
    'creator': {
        'id': 12,
        'name': "Alexander Polyanskikh"
      },
    'permissions': {
        'view': true,
        'edit': true,
        'edit_meta': true,
        'delete': true,
        'edit_perms': true,
        'inherited': false
      },
    'metadata': {
        'description': "~500 files inside",
        'crm_link': null
      }
}

Get folder path

GET /intranet/rest/documents/folder/:id/path

Returns the path trail to the folder with :id and information about all its parents.

Returns JSON-formatted array of objects in the following format:

[
  {
    'id': 15,
    'parent_id': 0,
    'obj_type': 'folder',
    'title': "Import from fs 2",
    'is_open': true
  },
  {
    'id': 350,
    'parent_id': 15,
    'obj_type': 'folder',
    'title': "images",
    'is_open': true
  }
]

Get document list

GET /intranet/rest/documents/folder/:id/documents

Has optional CGI-style parameters:

• metadata=:comma-separated metadata keys** - For example: ?metadata=description,comment
• num=:number - Max number of items to return, page size
• start=:number - Zero-based offset from which to start returning items list. Has effect only if num parameter is specified

Returns JSON-formatted array of documents. Each document has the following format:

     {
        'type': "document",
        'doc_id': 390,
        'version_num': 1,
        'parent_id': 15,
        'obj_type': 'document',
        'doc_type': 'standard',
        'URI': 'http://server.name/intranet/rest/documents/document/390',
        'title': "add_cat.php",
        'refcode': "Ref_390",
        'fsize': 143,
        'date_last_modified': {
            'date_str': "29-08-2011 13:43 NOVST",
            'timezone': "Asia/Novosibirsk",
            'date': "20110829064336"
          },
        'pc_title': "add_cat.php",
        'date_declared': null, 
        'date_created': {
            'date_str': "13-05-2011 18:12 NOVST",
            'timezone': "Asia/Novosibirsk",
            'date': "20110513111244"
          },
        'last_comment': "",
        'permissions': {
            'view': true,
            'edit': true,
            'edit_meta': true,
            'delete': true,
            'edit_perms': true,
            'inherited': false,
          },
        'creator': {
            'id': 12,
            'name': "Alexander Polyanskikh",
          },
        'metadata': {
            'description': "~500 files inside"
          }
      }

Get folder list

GET /intranet/rest/documents/folder/:id/folders

Has optional CGI-style parameters:

• metadata=:comma_separated_metadata_keys - For example: ?metadata=description,comment
• num=:number - Max number of items to return, page size
• start=:number - Zero-based offset from which to start returning items list. Has effect only if num parameter is specified

Returns JSON-formatted array of folders. Each folder has the following format:

     {
        'type': "folder",
        'id': 94,
        'parent_id': 15,
        'type': 'folder',
        'obj_type': 'folder',
        'URI': 'http://server.name/intranet/rest/documents/folder/94',
        'title': "images",
        'refcode': "fold_2",
        'date_last_modified': {
            'date_str': "13-05-2011 18:13 NOVST",
            'timezone': "Asia/Novosibirsk",
            'date': "20110513111313"
          },
        'date_closed': null,
        'date_created': {
            'date_str': "13-05-2011 18:13 NOVST",
            'timezone': "Asia/Novosibirsk",
            'date': "20110513111313"
          },
        'inactive': false,
        'permissions': {
            'view': true,
            'edit': true,
            'edit_meta': true,
            'delete': true,
            'edit_perms': true,
            'inherited': false
          },
        'creator': {
            'id': 12,
            'name': "Alexander Polyanskikh"
          },
        'metadata': {
            'description': "Folders metadata"
          },
      }

Get folder content (documents and folders)

GET /intranet/rest/documents/folder/:id

Has optional CGI-style parameters:

• metadata=:comma-separated_metadata_keys - For example: ?metadata=description,comment
• num=:number - Max number of items to return, page size
• start=:number. Zero-based offset from which to start returning items list. Has effect only if num parameter is specified

Returns JSON-formatted array of folders and documents. Folders returned first. Each returned record has the same format as described above - when only folders list of only documents list is requested.

Find subfolder by title or refcode

GET /intranet/rest/documents/folder/:id/subfolder?title=:title

GET /intranet/rest/documents/folder/:id/subfolder?refcode=:refcode

Tries to find a subfolder by its :title or :refcode. If no such folder is found the request returns error 404. If a folder is found, it returns information in the same format as when using /info path.

Document read operations

These operations are done using the GET request method.

All operations with individual document have the same syntax to specify document or its version. Here is the summary of methods:

/document/:doc_id/ Default method. Addresses latest version of document with any parent folder.

/document/:doc_id/:version_num/ Addresses specific version of document. Note: only the latest version can be checked out or modified.

/document/:doc_id/.../?parent_id=:parent_id Addresses the document in specific folder. Useful for documents located in more than one folder (linked to more than one folder).

Examples:

• /intranet/rest/documents/document/390/info - returns information about latest version of document with doc_id 390.
• /intranet/rest/documents/document/390/2/components - returns the list of components from the second version of document with doc_id 390.
• /intranet/rest/documents/document/390/2/file?parent_id=15 - returns primary component of the second version of document with doc_id 390, if it's located in folder with id 15.

Standard http error codes can be returned:

• 400 Bad Request
• 404 Not Found
• 403 Forbidden
• 501 Not Implemented

Get document info

GET /intranet/rest/documents/document/:doc_id/info

GET /intranet/rest/documents/document/:doc_id - alias for /info

Returns JSON-formatted array in the following format:

{
    'doc_id': 390,
    'version_num': 1,
    'date_declared': "",
    'pc_title': "add_cat.php",
    'parent_id': 15,
    'type': 'document',
    'obj_type': 'document',
    'doc_type': 'standard',   // this can be 'standard', 'marker' or something else
    'title': "add_cat.php",
    'refcode': "Ref_390",
    'description': "~500 files inside",
    'date_created': {
        'date_str': "13-05-2011 18:12 NOVST",
        'timezone': "Asia/Novosibirsk",
        'date': "20110513111244"
      },
    'date_last_modified': {
        'date_str': "13-05-2011 18:12 NOVST",
        'timezone': "Asia/Novosibirsk",
        'date': "20110513111244"
      },
    'creator': {
        'id': 12,
        'name': "Alexander Polyanskikh"
      },
    'permissions': {
        'view': true,
        'edit': true,
        'edit_meta': true,
        'delete': true,
        'edit_perms': true,
        'inherited': true
      },
    'metadata': {
        'description': "~500 files inside",
        'comment': "Version comment (first version)",
        'crm_link': null,
        'convert_to_pdf': "0"
      }
}

Components

A document version can be composed of one or more 'components'. Put another way, a document version can contain more than one file. Most of the time, a document version will refer to only one file, but in some cases it is useful to have a 'document' be comprised of multiple files - for example, an html file may also have some image files associated with it - the html file and images files together would be a document.

When there are multiple components in a document, one of them will be the primary component. This is the file that will be shown by default in Claromentis, or returned by default when making a REST request.

Get component list

GET /intranet/rest/documents/document/:doc_id/components

The components request returns a JSON-formatted array of all components of a document like this:

{
    '0': {
        'title': "version_two_of_document.docx",
        'size': 143,
        'URI': "http://server.name/intranet/rest/documents/document/390/file/version_two_of_document.docx",
        'primary': true
      },
    '1': {
        'title': "version_one_of_document.docx",
        'size': 3757,
        'URI': "http://server.name/intranet/rest/documents/document/390/file/version_two_of_document.docx",
      }
}

Get document content

Primary component:

GET /intranet/rest/documents/document/:doc_id/file

Any component:

GET /intranet/rest/documents/document/:doc_id/file/:component_name

Returns the component body without any special encoding or wrapping.

Versions

When you check out and then check in a document you create a new 'version' of the document. A document can have multiple versions, with one version being the latest that is shown by default in Claromentis or returned by default by a REST request. In all document REST requests you can optionally specify the version of a document that you want, otherwise the default (latest) version will be returned.

Get version list

GET /intranet/rest/documents/document/:doc_id/versions

Returns JSON-formatted array of document versions. Each version is JSON array like this:

{
    'version_num': 2,
    'is_latest': true,   // only one of listed versions is marked as latest
    'title': "404.php",
    'date_last_modified': {    // when this version was created
        'date_str': "29-08-2011 13:43 NOVST",
        'timezone': "Asia/Novosibirsk",
        'date': "20110829064336"
      },
    'modified_by': {           // who has created this version
        'id': 12,
        'name': "Alexander Polyanskikh"
      },
    'version_comment': "Improved errors handling",
    'URI': "http://server.name/intranet/rest/documents/document/389/2/"
}

Files drop box

Drop box is a temporary location where files can be uploaded and later used as documents content (components) during check-in or when a new document is added. Each uploaded file is given unique key which is used to refer that file in other REST requests.

The main operations are:

• POST /intranet/rest/documents/dropbox
• GET /intranet/rest/documents/dropbox
• DELETE /intranet/rest/documents/dropbox/:file_key

Add a file to drop box

POST /intranet/rest/documents/dropbox

Entire request body is saved as a new file in the drop box and file key with some other information is returned:

{
    'file_key': "5bcae0cadfea12b9a3319d3a1cd0c466"
    'URL': "http://server.name/intranet/rest/documents/dropbox/5bcae0cadfea12b9a3319d3a1cd0c466"
}

On error returns status code 500.

Uploading a file this way is not the same as using HTTP file upload. File should be sent as a binary stream in request body without any encoding.

List uploaded files

GET /intranet/rest/documents/dropbox

Returns a JSON-formatted array with a list of files currently uploaded into drop box by current user. Each file is a JSON array with this structure:

{
    'file_key': "5bcae0cadfea12b9a3319d3a1cd0c466",
    'name': null,
    'size': 24914,
    'date': {
        'date_str': "30-08-2011 18:12 NOVST",
        'timezone': "Asia/Novosibirsk",
        'date': "20110830111227"
      },
    'URI': "http://server.name/intranet/rest/documents/dropbox/5bcae0cadfea12b9a3319d3a1cd0c466"
}

Delete a file

DELETE /intranet/rest/documents/dropbox/:file_key

Delete a previously uploaded file from drop box.

Normally, uploaded files are automatically deleted after being used for updating or creating a new document. Files uploaded but not used for a long time are also deleted automatically after some amount of time.

If successful, request returns http code 204, without any data in body. If a file with the given key doesn't exist or belongs to another user, status code 500 is returned.

Editing documents

To create a new version of an existing document it should be checked out and then checked in. Checking out prevents multiple people from editing the same document and overwriting each others changes.

During check-in, all file components should be first uploaded into the drop box, then their file_keys used for actual check-in.

Check out a document

POST /intranet/rest/documents/document/:doc_id/checkout[?parent_id=:parent_id] POST /intranet/rest/documents/checkout/:doc_id[?parent_id=:parent_id]

Check out a document. The two requests above are equivalent.

To mark a document as being edited by the current user. The :parent_id part in square brackets is optional and denotes the id of the parent folder of the document where the document is to be checked out. This is useful if the document is located in different folders and has different permissions there. The current user can check out the document only in context of specified folder.

Status code 204 is returned on success. The document body is not returned, as in the normal web interface. The document can be downloaded independently.

Error 403 is returned if the document cannot be checked out because of its permissions or some other property (for example, markers cannot be checked out). Other standard errors also can be returned - 400 Bad Request and 404 Not Found are two examples.

List of checked out documents

GET /intranet/rest/documents/checkin

Returns a JSON-formatted array of documents checked out by current user. Each document is a JSON array in this format:

{
    'doc_id': 394,
    'parent_id': 15,
    'title': "add_marker.php",
    'description': "~500 files inside",
    'URI': "http://server.name/intranet/rest/documents/document/394?parent_id=15",  // document details URI
    'checkin_URI': "http://server.name/intranet/rest/documents/checkin/394"         // URI used to check-in document or cancel editing
}

Cancel editing

DELETE `/intranet/rest/documents/checkin/:doc_id

Cancel editing a document and unblock it so other users can check it out.

Only the person who checked out a document can cancel editing.

On success returns status code 204.

On error returns 403 Forbidden. Also can return standard codes 400 Bad Request and 404 Not Found.

Check in a document

POST /intranet/rest/documents/checkin/:doc_id

Check in a new version of document.

The request body should contain JSON-formatted data with information about the new version. Components are specified by their files keys as returned by drop box when uploading them. Request format is the following:

{
    "comment": "Version comment",
    "new_title": "New_doc_title.doc", // optional - allows renaming the document together with creating a new version
    "is_draft" : 1,
    "components": [
        {
            "file_key": "5bcae0cadfea12b9a3319d3a1cd0c466",
            "is_primary": true
        },
        {
            "file_key": "fdd79f031b5861c73299dbc3bdfbcfc1",
            "name": "image.jpg"   // name is optional - see below for explanation
        }
      ]
}

When a document is checked in as a draft, the current live version of the document will remain in the main document listing and a new draft version will be created.

The check in request may contain one or more components. If more than one component is given a multi-component document is created. The component with is_primary set to true will be marked as the primary component and will be the file shown by default in the Claromentis front-end and returned in REST API requests.

The component name is picked using these rules:

• If only one component is given, The name is copied from document name
• If a component is primary and its name is not specified, it's copied from document name
• if more than one components are given and they have names, the components are saved under those names
• if component is not primary and name is not specified, a random name is assigned

Draft Documents

Draft document approval and rejection

In the process of being uploaded or checked in, a document can be marked as having draft status. Draft documents do not appear in the live file list for their folder until they are approved. If a live document is checked out, then checked in as a draft, the current live version of the document will continue to appear in the folder's file list until the draft version is approved.

Draft documents must be approved by a user with edit permissions on the folder where they reside before they can become live. If a draft is rejected it is deleted. A person with draft upload rights is also able to reject their own draft documents.

Creating draft documents

Documents can be uploaded in draft status by calling:

POST intranet/rest/documents/folder/:id/documents/

...including is_draft set to true in the request body.

For full documentation on creating documents with draft status, see the Add documents and folders section below.

Get a list of drafts

GET /intranet/rest/documents/folder/:folder_id/documents/?draft=1

This call returns an array of drafts that the current user has created across all folders (the folder_id is ignored). The response is in JSON format as follows:

[
    {
        "doc_id": "172",
        "title": "A_Draft_Document.docx",
        "parent_id": "3",
        "version_num": "1",
        "can_delete": 1,
        "can_approve": 1
    },
    {
        "doc_id": "173",
        "title": "Another_Draft_Document.docx",
        "parent_id": "3",
        "version_num": "1",
        "can_delete": 1,
        "can_approve": 1
    }
]

Reject a draft

DELETE /intranet/rest/documents/document/:doc_id/:version_num

Rejecting a draft document is equivalent to deleting a version of a document. If the version of the document specified is a draft, the deletion is processed as a rejection, that is, the document is deleted and the correct notifications are sent.

The current user must have permission to reject the current draft associated with doc_id and version_num. When rejecting a draft, a notification will be sent to the user who uploaded the draft to inform them that their draft was rejected.

Users who upload draft documents are able to reject/delete their own draft documents without having document deletion permissions.

Result of operation is indicated by response code:

• 204 No content draft successfully rejected
• 403 Forbidden currently logged on user doesn't have rights to reject this draft
• 500 Internal Server Error other errors.

Get a list of documents awaiting approval

GET /intranet/rest/documents/folder/:folder_id/documents/?to_approve=1

Returns a list of documents the current user has rights to approve across all folders (folder_id is ignored). The returned data is in JSON format as follows:

[
    {
        "doc_id": "172",
        "title": "ADraftDocument.docx",
        "parent_id": "3",
        "version_num": "1",
        "can_approve": 1,
        "can_delete": 1
    },
    {
        "doc_id": "173",
        "title": "AnotherDraftDocument.docx",
        "parent_id": "3",
        "version_num": "1",
        "can_approve": 1,
        "can_delete": 1
    }
]

Approve a draft

PUT /intranet/documents/document/:doc_id/approve

To approve a draft a user must have edit rights on the folder where the document resides. The GET call above can be used to return the list of documents the current user has approval/rejection rights over.

When a document is approved it will appear in the file list for its parent folder and a notification will be sent to the user who uploaded the draft to inform them their document has gone live.

Result of operation is indicated by response code:

• 204 No content draft successfully approved
• 403 Forbidden currently logged on user doesn't have rights to approve the draft
• 500 Internal Server Error other errors.

Add documents and folders

Folders and documents are added into folder by submitting JSON-formatted data this way:

POST /intranet/rest/documents/folder/:id/ - accepts both folders and documents

POST /intranet/rest/documents/folder/:id/folders/ - can be used to create only folder

POST /intranet/rest/documents/folder/:id/documents/ - can be used to create only documents

These requests add a new folder or a document into folder specified by :id parameter in URL. Note, it's not possible to add top-level folder this way. Top-level folders can only be created using web interface.

The request body should have the following JSON format:

{
    "title": "New name",
    "refcode": "Dir_15",
    "type": "folder",
    "doc_type": "standard",
    "is_draft": true,
    "metadata": {
        "metadata_name":{:metadata_value},
        "metadata_name":{:metadata_value}
      },
    "components": [
        {
            "file_key": "5bcae0cadfea12b9a3319d3a1cd0c466",
            "is_primary": true
        },
        {
            "file_key": "fdd79f031b5861c73299dbc3bdfbcfc1",
            "name": "image.jpg"
        }
      ]
}

And a simple example for uploading a single file

{
    "title": "A new file.doc",
    "refcode": "REF_1",
    "type": "document",
    "doc_type": "standard",
    "is_draft": false,
    "components": [
        {
            "file_key": "ASvVhDNN1COpao3gfqZt1SVOpwwRODSc",
            "is_primary": true
        }
      ]
}

For metadata, see the dedicated section for it. For more information about file components, see the document check in section.

Upon successful addition, the new object information is returned in the same format as /document/:doc_id/info and /folder/:id/info.

Update folder and document properties

Folders and documents properties are updated by sending PUT requests.

PUT /intranet/rest/documents/folder/:id/info/

PUT /intranet/rest/documents/document/:doc_id/info/

PUT /intranet/rest/documents/document/:doc_id/ - alias for /info

Update document details

PUT /intranet/rest/documents/document/:doc_id/info/

PUT /intranet/rest/documents/document/:doc_id/ - alias for /info

Rename, update document refcode, metadata and all other basic details.

The request body should contain JSON-formatted data with the information to update:

{
    "title": "New name",
    "refcode": "new_refcode",
    "metadata": {
        "metadata_name":{:metadata_value},   // metadata. See separate section about metadata format
        "metadata_name":{:metadata_value}
      },
    "record_types": {
        "record_type_id": {
            "metadata_name":{:metadata_value},
            "metadata_name":{:metadata_value}
          },
        "record_type_id": {
            "metadata_name":{:metadata_value},
            "metadata_name":{:metadata_value},
          }
      }
}

All parameters are optional.

If metadata name is not specified (in both standard and record type metadata), it's not changed. Only existing record types can be updated. If specified record type is not assigned to this document, it's silently ignored. Find out more about managing metadata.

Update folder details

PUT /intranet/rest/documents/folder/:id/info/

Rename, update folder refcode, metadata - all basic details.

Request body should contain JSON-formatted data with the information to update. Request format is the following:

{
    "title": "New name",
    "refcode": "new_refcode",
    "metadata": {
        "metadata_name":{:metadata_value},   // metadata. See separate section about metadata format
        "metadata_name":{:metadata_value}
      }
}

All parameters are optional.

If metadata name is not specified (in both standard and record type metadata), it's not changed.

Deleting folders and documents

Documents and folders are deleted by sending DELETE request. If optional CGI-style parameter no_trash_can is set to 1, the document/folder will be deleted permanently. Otherwise it'll be moved to the trash can.

Result of operation is indicated by response code:

• 204 No content document/version/folder successfully deleted
• 403 Forbidden currently logged on user doesn't have rights to delete this object
• 500 Internal Server Error other errors.

Standard response codes 400 Bad Request and 404 Not Found also can be returned if request is malformed or requested object doesn't exist.

Delete a document

DELETE /intranet/rest/documents/document/:doc_id/ - delete entire document

DELETE /intranet/rest/documents/document/:doc_id/:version_num/ - delete single document version

Optional CGI-style parameter no_trash_can can be set to 1 to prevent document from being placed into trash can and just delete it permanently. For example:

DELETE /intranet/rest/documents/document/422/2/?no_trash_can=1 - permanently delete 2nd version of document.

As with reading documents it's possible to specify document parent folder by adding CGI-style parameter parent_id. This is especially useful when document is linked into a few folders. If parent_id is not given, a random parent will be selected. Obviously this is not very useful when document is located in more than one folder, but it's fine for documents located only in one folder which is usually the case.

Note: as from Claromentis 6.2. The document is not moved into trash can if it's located in more than one folder and deleted only from one of them. It's just permanently unlinked from the specified folder and stays as a normal document in other folders. "no_trash_can" parameter has no effect in this case.

Delete a folder

DELETE /intranet/rest/documents/folder/:id/

Deletes entire folder and all its content.

Optional CGI-style parameter "no_trash_can" can be set to 1 to prevent folder from being placed into trash can and just delete it permanently. For example:

DELETE /intranet/rest/documents/folder/14/?no_trash_can=1 - permanently delete folder with id 14.

Copy/move/link documents and folders

POST /intranet/rest/documents/copy/

POST /intranet/rest/documents/move/

POST /intranet/rest/documents/link/

These three methods do mass operations on specified objects that can be both documents and folders. They accept parameters in request body in a similar format and return results the same way. Structure of the request body is:

{
    "objects": [
        :object_spec, // see below
        :object_spec, // see below
        ...
    ],
    "destination": :destination_folder_spec,
    "comment": "operation comment" // optional
}

The destination folder can be specified either with its REST resource URL (/intranet/rest/documents/folder/4321) or just a folder ID.

object_spec is more complex. Each of these points to a document or a folder, using either its REST resource URL or by its properties. If it's a resource URL then the entire :object_spec is just a string like /intranet/rest/documents/folder/1234/ or /intranet/rest/documents/document/123?parent_id=1234. If the object is specified by its properties, its a JSON object with the following structure:

// For folders:
{
    "type": "folder",
    "id": 123,
}

// For documents
{
    "type": "document",
    "id": 123,
    "parent_id": 1234 // parent folder id
}

Note, even though specifying parent_id for documents is optional, it's really important to give it if a document is linked to multiple folders. Otherwise the document can be removed from the wrong folder (after the "move" operation).

Returned data

These calls always return HTTP status code 204.

Type reference

Date and time

When date with time is returned from a REST call, it's always returned as an object (associative array) with these properties (keys):

• date_str - A human-readable string representation of date. It's formatted according to the "datetime" format string specified in the main Claromentis config file.
• timezone - The current user's timezone. The "time_str" string above shows time in this timezone
• date - 14-digit absolute date and time. Note, it's UTC time.

Date

When date is returned from a REST call, it's always returned as an object (associative array) with these properties (keys):

• date_str - human-readable string representation of date. It's formatted according to "long_date" format string specified in the main Claromentis config file
• date - 8-digit date. Refer [[claromentis:development:dates#dates_without_time|dates without time]] page for more details about this format.

Metadata

See detailed description of metadata in the REST APIs.