REST Web Service
From KnowledgeTree Community
Contents |
The REST framework
The REST web service framework uses PHP5's reflection capabilities to implement the functionality in the API.
Using REST
REST can be run using curl, through a browser or via a REST client.
Response formats
The response can be either xml or json and will be in the following format:
[response]
- [status_code] => the response status, a 0 indicates success
- [message] => contains the error message if an error has occurred
- [results] => contains the results of the request query
Invalid Session Response
The xml response for a method called using an incorrect or invalid session id would be:
<response>
<message>API could not be authenticated: Session is invalid</message>
<status_code>1</status_code>
</response>
Session Id's
A session_id is generated on a call to login.
Examples:
Basics
Lets base the examples on the following tree view:
Where a folder is denoted with a trailing "/", and prefixed with an ID number.
Documents are listed with their ID and no trailing "/".
1 Root/ 2 Accounting/ 8 Invoices/ 23 INV 100 24 INV 101 25 INV 102 9 Quotes/ 26 QUO 200 27 QUO 200 4 Human Resources/ 12 Staff/ 31 S001 32 S002 33 S003 13 Agencies/ 34 AGN 500 35 AGN 501 36 AGN 502 42 Shortcut To Accounting 5 Marketing/ 37 MAR 601 6 Planning/ 14 Architecture/ 38 ARC 700 15 Road Map/ 39 RDM 700 7 Quality Assurance/ 16 Version 3.0.0/ 40 VER 800 41 README.txt 22 Trash/
The following examples use curl to access the REST API.
The base url for accessing the REST API is:
$server_url = 'http://server.domain/ktwebservice/KTWebService.php?';
Login
Login and authenticate
$url = $server_url.'method=login&password=admin&username=admin';
// Push the url through curl
$response = call_curl_function($url);
The response will have the following xml format:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
22a090a8f8e2ddacffd4be18cdc3589d
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
On success the session id is returned as shown below and can be used for the functions called in the session.
$session_id = $response['results'];
Logout
Logging out will cause the session to end and the session id will be invalid.
$url = $server_url.'method=logout&session_id='.$session_id;
$response = call_curl_function($url);
The xml response will return a status_code of 0 to indicate a successful logout:
<response>
<status_code>0</status_code>
</response>
Error Checking
After each call to the web service, it would be nice to check that no error has occured.
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. 0 indicates success. On failure the error message will be contained in the message tag.
if($response['status_code'] != 0){
return 'Error - authentication failed: '.$response['message'];
}
All the examples that follow, should do an error check to validate that the actions were successful.
Folder Actions
Get Folder Details
Retrieve folder details.
Using the $session_id in Login section.
To get the details for the Accounting(id of 2), the function / method KTAPI::get_folder_detail($folder_id) can be used:
$url = $server_url.'method=get_folder_detail&session_id='.$session_id.'&folder_id=1';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<id>2</id>
<folder_name>Accounting</folder_name>
<parent_id>1</parent_id>
<full_path>Accounting</full_path>
<permissions>RWA</permissions>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder details are returned in $response['results'].
Get Folder Shortcuts
Retrieves all shortcuts linking to a specific folder.
Using the $session_id in Login section.
To get the shortcuts for the folder Accounting(id of 2), the function / method KTAPI::get_folder_shortcuts($folder_id) can be used:
$url = $server_url.'method=get_folder_shortcuts&session_id='.$session_id.'&folder_id=2';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<item>
<id>42</id>
<name>Shortcut to Accounting</name>
<description>description of shortcut</description>
<parent_id>4</parent_id>
<creator_id>1</creator_id>
<is_public>0</is_public>
<parent_folder_ids>1,12</parent_folder_ids>
<full_path>shortcut to testing</full_path>
<permission_object_id>1</permission_object_id>
<permission_lookup_id>6</permission_lookup_id>
<restrict_document_types>0</restrict_document_types>
<owner_id/>
<linked_folder_id>5</linked_folder_id>
</item>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder shortcuts details are returned in $response['results'] as a list of items.
Get Folder Details By Name
Retrieve folder details given a folder name, which could include a full path.
Using the $session_id in Login section.
To get the details for the folder Marketing, the function / method KTAPI::get_folder_detail_by_name($folder_name) can be used:
$url = $server_url.'method=get_folder_detail_by_name&session_id='.$session_id.'&folder_name=Marketing';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<id>5</id>
<folder_name>Marketing</folder_name>
<parent_id>1</parent_id>
<full_path>Marketing</full_path>
<permissions>RWAND</permissions>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder details are returned in $response['results'].
Get Folder Contents
Retrieve the contents of a folder.
Using the $session_id in Login section.
To get the contents for the Quality Assurance (id of 7), the function / method KTAPI::get_folder_contents($folder_id, $depth='1', $what='DFS') can be used. The extra parameter, $depth, determines if direct contents ($depth = 1) or contains of contained folders are returned. By default direct contents are returned. The extra parameter, $what, determines if documents, folders or shortcuts are returned. By default all three are returned.
$url = $server_url.'method=get_folder_contents&session_id='.$session_id.'&folder_id=7';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<folder_id>7</folder_id>
<folder_name>Quality Assurance</folder_name>
<full_path>Quality Assurance</full_path>
<items>
<item>
<id>16</id>
<item_type>F</item_type>
<custom_document_no>n/a</custom_document_no>
<oem_document_no>n/a</oem_document_no>
<title>Version 3.0.0</title>
<document_type>n/a</document_type>
<filename>DroppedDocuments</filename>
<filesize>n/a</filesize>
<created_by>Administrator</created_by>
<created_date>n/a</created_date>
<checked_out_by>n/a</checked_out_by>
<checked_out_date>n/a</checked_out_date>
<modified_by>n/a</modified_by>
<modified_date>n/a</modified_date>
<owned_by>n/a</owned_by>
<version>n/a</version>
<is_immutable>n/a</is_immutable>
<permissions>RWAND</permissions>
<workflow>n/a</workflow>
<workflow_state>n/a</workflow_state>
<mime_type>folder</mime_type>
<mime_icon_path>folder</mime_icon_path>
<mime_display>Folder</mime_display>
<storage_path>n/a</storage_path>
<items/>
</item>
<item>
<id>41</id>
<item_type>D</item_type>
<custom_document_no>n/a</custom_document_no>
<oem_document_no>n/a</oem_document_no>
<title>README.txt</title>
<document_type>Default</document_type>
<filename>README.txt</filename>
<filesize>1024</filesize>
<created_by>Administrator</created_by>
<created_date>2009-05-13 09:30:35</created_date>
<checked_out_by>n/a</checked_out_by>
<checked_out_date>n/a</checked_out_date>
<modified_by>Administrator</modified_by>
<modified_date>2009-05-13 09:30:35</modified_date>
<owned_by>Administrator</owned_by>
<version>0.1</version>
<content_id>2</content_id>
<is_immutable>false</is_immutable>
<permissions>RW</permissions>
<workflow>n/a</workflow>
<workflow_state>n/a</workflow_state>
<mime_type>application/octet-stream</mime_type>
<mime_icon_path>unspecified_type</mime_icon_path>
<mime_display>Binary File</mime_display>
<storage_path>00/2</storage_path>
<items/>
</item>
<items/>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder contents are returned in $response['results'] as a list of items.
The item_type specifies whether its a folder or a document, either F or D, respectively.
Create Folder
To create a new folder Leave Register in the folder Human Resources (id of 4), the function / method KTAPI::create_folder($folder_id, $folder_name, $sig_username = , $sig_password = , $reason = ) can be used:
$url = $server_url.'method=create_folder&session_id='.$session_id.'&folder_id=4&folder_name=Leave Register&sig_username=uname&sig_password=pswrd&
reason=areason';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<id>5</id>
<folder_name>Leave Register</folder_name>
<parent_id>4</parent_id>
<full_path>Human Resources/Leave Register</full_path>
<permissions>RWAND</permissions>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder details are returned in $response['results'].
Create Folder Shortcuts
To create a shortcut of the Human Resources(id of 4) folder in folder Accounting(id of 2), the function / method KTAPI::create_folder_shortcut($target_folder_id, $source_folder_id, $sig_username = , $sig_password = , $reason = ) can be used:
$url = $server_url.'method=create_folder_shortcut&session_id='.$session_id.'&target_folder_id=4&source_folder_id=2&sig_username=uname
&sig_password=pswrd&reason=areason';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<id>19</id>
<folder_name>Human Resources</folder_name>
<parent_id>2</parent_id>
<full_path>Accounting/Human Resources</full_path>
<permissions>RWAND</permissions>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder shortcut is returned in $response['results'].
Delete Folders
To delete the folder Trash(id of 22), the function / method KTAPI::delete_folder($folder_id, $reason, $sig_username = , $sig_password = ) can be used:
$url = $server_url.'method=delete_folder&session_id='.$session_id.'&folder_id=22&reason=areason&sig_username=uname&sig_password=pswrd';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder is delete.
Rename Folders
To rename the folder Planning(id of 6), the function / method KTAPI::rename_folder($folder_id, $newname, $sig_username = , $sig_password = , $reason = ) can be used:
$url = $server_url.'method=rename_folder&session_id='.$session_id.'&folder_id=6&newname=Planning&sig_username=Planning 2009
&sig_password=pswrd&reason=areason';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the folder is renamed.
Copy Folders
To copy the folder Marketing(id of 3) to the folder Human Resources(id 0f 4) the function / method KTAPI::copy_folder($source_id, $target_id, $reason, $sig_username = , $sig_password = ) can be used:
$url = $server_url.'method=copy_folder&session_id='.$session_id.'&source_id=3&target_id=4&reason=areason&sig_username=uname&sig_password=pswrd';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<results>
<id>38</id>
<folder_name>testing</folder_name>
<parent_id>8</parent_id>
<full_path>testing 2/testing</full_path>
<permissions>RWAND</permissions>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the copied folders details are returned in $response['results'].
Move Folders
To move the folder Quotes(id of 9) to the folder Marketing(id 0f 5) the function / method KTAPI::move_folder($source_id, $target_id, $reason, $sig_username = , $sig_password = ) can be used:
$url = $server_url.'method=move_folder&session_id='.$session_id.'&source_id=9&target_id=5&reason=areason&sig_username=uname&sig_password=pswrd';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<results>
<id>2</id>
<folder_name>Quotes</folder_name>
<parent_id>5</parent_id>
<full_path>Marketing/Quotes</full_path>
<permissions>RWAND</permissions>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the moved folders details are returned in $response['results'].
Document Actions
Create Document Shortcuts
To create a shortcut of the document INV 100(id of 23) in folder Planning(id of 6), the function / method KTAPI::create_document_shortcut($target_folder_id, $source_document_id, $sig_username = , $sig_password = , $reason = ) can be used:
$url = $server_url.'method=create_document_shortcut&session_id='.$session_id.'&target_folder_id=6&source_document_id=1
&sig_username=uname&sig_password=pswrd&reason=areason';
$response = call_curl_function($url);
The xml response will be as follows:
<response>
<status_code>
0
</status_code>
<message>
</message>
<results>
<document_id>44</document_id>
<custom_document_no>n/a</custom_document_no>
<oem_document_no>n/a</oem_document_no>
<title>adocument</title>
<document_type>Default</document_type>
<filename>INV 100</filename>
<filesize>1024</filesize>
<folder_id>2</folder_id>
<created_by>Administrator</created_by>
<created_date>2009-05-13 09:30:36</created_date>
<checked_out_by>n/a</checked_out_by>
<checked_out_date>n/a</checked_out_date>
<modified_by>Administrator</modified_by>
<modified_date>2009-05-13 09:30:36</modified_date>
<owned_by>Administrator</owned_by>
<version>0.1</version>
<content_id>1</content_id>
<is_immutable/>
<permissions>RW</permissions>
<workflow>n/a</workflow>
<workflow_state>n/a</workflow_state>
<full_path>/Planning/INV 100</full_path>
<mime_type>application/octet-stream</mime_type>
<mime_icon_path>unspecified_type</mime_icon_path>
<mime_display>Binary File</mime_display>
<storage_path>00/5</storage_path>
</results>
</response>
Convert the xml to an array for use in php.
$response = call_xml2array_function($response);
$response = $response['response'];
Check the status_code to determine if an error occurred. (Error Checking Section)
On success, the document shortcut is returned in $response['results'].
del.icio.us
digg
reddit
facebook
stumbleupon
