A www.project-open.net /en/package-intranet-rest /web/projop/www-httrack/www.project-open.net/en/package-intranet-rest.html www.project-open.net / If-Modified-Since: Tue, 28 Jun 2016 06:58:11 GMT x 2rW P_ OK text/html utf-8 Tue, 28 Jun 2016 08:18:58 GMT 2rW
The ]po[ "intranet-rest" package implements a Web-Service that exposes most of the ]project-open[ system to external applications that need to read and write ]po[ objects.
The ]po[ “intranet-rest” package allows 3rd party applications to integrate conveniently with a ]project-open[ backend application. External applications are allowed to Create, Read, Update and List important ]po[ objects.
|
HTTP “GET” | HTTP “POST” |
Object Type
Resource |
“L=Lists”:
Lists all object of that object type. |
“C=Create”:
Creates a new instance of the object type. |
Individual Object
Resource |
“R=Read”:
Retrieves all fields of the specified object |
“U=Update”:
Updates the specified object. |
“D=Delete”: Delete ("nuke") operations are not supported with this REST interface for the same reasons deleting is not supported via the Web GUI.
Please visit PO Time Sheet @ SourceForge to get an idea about what is possible using the ]po[ REST interface.
"]po[ Time Sheet" is a Java client application for Windows, Linux and Mac OSX that allows a user to log hours against a project hierarchy. It is also capable to browse a great part of the ]po[ object types and shows objects in a table view.
The application has been written as a reference application. Users can obtain the source code for Eclipse easily via a CVS checkout.
(A screen shot of the time sheet logging screen)
The ]po[ "intranet-rest" package is part of the ]po[ V4.0 release, so that you don't need to download the package. Please note that the REST interface for ]po[ V3.5 was experimental and has several known issues, so that we strongly suggest to develop with ]po[ V4.0.
The following application scenarios are supported by the ]po[ REST interface:
The REST Web-service was designed to fulfill the following goals:
The ]po[ REST protocol (the names and structure of the tags sent and received) is released in versions. Version numbers consist of two digits (for example: "1.0"):
To get the server version number please visit the URL http://<your_server>/intranet-rest/version.
Please see the |REST version history.
Please note that not all ]po[ objects support a C=Create operation. This is because create operations need to be coded manually, as opposed to the automatic processing of RUL operations via the ]po[ DynField SQL metadata system.
Authentication of the REST API is managed per user. Users are granted the same access right as with the Web GUI. This mechanism includes the case of external users including customers and providers.
The REST WS provides a choice of three different authentication mechanisms:
BASIC HTTP Authentication is defined in RFC 2617 (http://www.ietf.org/rfc/rfc2617.txt) and explained in http://en.wikipedia.org/wiki/Basic_access_authentication. ]po[ accepts standard username/password or email/password combinations.
The following example assumes that the user “Ben Bigboss” has username=bbigboss and password=ben. Getting the list of all projects accessible for Ben Bigboss using the “wget” command line utility (available on Linux and CygWin for Windows):
wget -O - --user=bbigboss --password=ben http://192.168.140.128:8000/intranet-rest/im_project
Depending on your version of "wget" , you may have add the option "--auth-no-challenge" to your wget command.
The output will look like:
<?xml version='1.0'?> <object_list> <object_id href="http://192.168.140.128::8000/intranet-rest/im_project/13074">13074</object_id> . . . </object_list>
“OpenACS Cookie Authentication” represents the standard OpenACS authentication. You are automatically authenticated when you have entered your email/password at the ]po[ application. Then please enter to the local URL /intranet-rest/ in your local server.
As a result, you will see a HTML view to the REST interface, allowing you to browse the data in HTML mode.
An "auto-login token" is a hashed password. The auto-login authentication mechanism allows to authenticate a user with URL parameters, making it the ideal mechanism for AJAX interfaces etc.
To determine your user's auto-login token please enter the URL: /intranet-rest/auto-login. This page will return an auto-login token for your user like this one:
The /intranet-rest/auto-login?format=xml will return the auto_login token in XML format.
Now you can get the list of all projects accessible for Ben Bigboss using the “wget” command line utility by passing the user_id and the auto_login token as part of the URL:
wget -O - "http://192.168.140.128:8000/intranet-rest/im_project?user_id=8864&auto_login=6AD9391BE60089BBD551AE9535775EFE78A9AB5C"
Please observe the double quotes (“”) round the URL, because the “&” has a special meaning as part of a Linux command line.
The REST interface allows to set permissions per object type and user group, effectively allowing users to use client-side applications, widgets etc. using the REST interface, instead of the normal Web GUI.
The screenshot below shows the REST permission administration screen. In this screen you can set R=Read and W=Write permissions per object type and user profile.
Special permissions apply to the following object types:
These object types feature per-user permission in addition to the per-user-profile permission set in the administration screen below.
In the same way as project and the other objects can be limited to individual users being a "member" of a project in the Web GUI, these permissions apply in the REST interface. So a user effectively needs two permissions to R=Read a project:
The REST interface returns standard HTTP error codes:
In case of an error, there will be an explicit error message:
<?xml version='1.0' encoding='UTF-8'?> <error> <http_status>403</http_status> <http_status_message> Forbidden: The request is understood, but it has been refused. </http_status_message> <request> /intranet-rest/im_project?query=project%5fstatuss%5fid+in+%2876%2c71%29 </request> <message> The specified query is not a valid SQL where clause: 'project_status_id = (76,71)‘ </message> </error>
Not all ]po[ object types are supported by the REST interface, and not all object types currently support all CRUL operations. The following table specifies the current status of the interface:
Kind: | Publicity: |
---|---|
[Library Files | Procedures | SQL Files | Content Pages] | [Public Only | All] |
TCL Libraries
tcl/intranet-rest-create-procs.tcl REST Web Service Component Library tcl/intranet-rest-data-source-procs.tcl REST Web Service Component Library tcl/intranet-rest-get-procs.tcl REST Web Service Component Library tcl/intranet-rest-post-procs.tcl REST Web Service Component Library tcl/intranet-rest-procs.tcl REST Web Service Component Library tcl/intranet-rest-sql-parser-procs.tcl REST Web Service Library Utility functions tcl/intranet-rest-util-procs.tcl REST Web Service Library Utility functions tcl/intranet-rest-validator-procs.tcl REST Web Service Validator
TCL Procedures
im_quotejson Quote a JSON string. im_rest_deref_plpgsql_functions Returns a key-value list of dereference functions per table-column. im_rest_doc_return This is a replacement for doc_return that values if the gzip_p URL parameters has been set. im_rest_error Returns a suitable REST error message im_rest_get_content There's no [ns_conn content] so this is a hack to get the content of the REST request. im_rest_get_rest_columns Reads the "columns" URL variable and returns the list of selected REST columns or an empty list if the variable was not specified. im_rest_hard_coded_deref_plpgsql_functions Returns a key-value list of hard coded attribues per object type. im_rest_normalize_timestamp Reformat JavaScript date/timestamp format to suit PostgreSQL 8.4/9.x im_rest_object_type_columns Returns a list of all columns for a given object type. im_rest_object_type_index_columns Returns a list of all "index columns" for a given object type. im_rest_object_type_order_sql returns an "ORDER BY" statement for the *_get_object_type SQL. im_rest_object_type_pagination_sql Appends pagination information to a SQL statement depending on URL parameters: "LIMIT $limit OFFSET $start". im_rest_object_type_select_sql Calculates the SQL statement to extract the value for an object of the given rest_otype. im_rest_object_type_update_sql Updates all the object's tables with the information from the hash array. im_rest_parse_json_content Parse the JSON content of a POST request with the values of the object to create or update. im_rest_project_task_tree_action Create, Update or Delete a task coming from TreeStore im_rest_project_task_tree_assignees Update the resource assignees to the task im_rest_project_task_tree_create Create a new task coming from TreeStore im_rest_project_task_tree_delete Delete a task coming from TreeStore im_rest_project_task_tree_update Update a task coming from TreeStore im_rest_valid_sql Returns 1 if "where_clause" is a valid where_clause or 0 otherwise. sql_assert Checks that the string str is of sql type "type". sql_between sql_compare sql_containing sql_exact sql_from_table_reference sql_function sql_function_count sql_in sql_integer sql_keyword sql_like sql_name sql_non_assert Checks that the string str is NOT of sql type "type". sql_operator sql_procedure_end sql_search_condition sql_search_value sql_select sql_starting sql_test Executes a number of checks sql_value_litteral
SQL Files
sql/postgresql/intranet-rest-create.sql sql/postgresql/intranet-rest-drop.sql sql/postgresql/upgrade/upgrade-4.0.3.0.2-4.0.3.0.3.sql sql/postgresql/upgrade/upgrade-4.1.0.0.0-4.1.0.0.1.sql
www/ | |
auto-login.adp | |
auto-login.tcl | Home page for REST service, when accessing from the browser. |
data-source/ | |
cost-center-tree.json.tcl | Returns a JSON tree structure suitable for batch-loading a cost center TreeStore |
domain-proxy.adp | |
domain-proxy.tcl | Fetches a page from www.project-open.net |
project-task-tree-action.adp | |
project-task-tree-action.tcl | |
project-task-tree.json.adp | |
project-task-tree.json.tcl | Returns a JSON tree structure suitable for batch-loading a project TreeStore |
success.adp | |
dynfield-widget-values.adp | |
dynfield-widget-values.tcl | |
index.adp | |
index.tcl | |
version.adp | |
version.tcl |
Calle Aprestadora 19, 12o-2a
E-08907 Hospitalet de Llobregat (Barcelona)
Tel Europe: +34 932 202 088
Tel US: +1 415 429 5995
Mail: info@project-open.com