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.
Use "--no-check-certificate" if you use a self-signed certificate.
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:
tcl/intranet-rest-authentication-procs.tcl REST Web Service Component Library - Authentication 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
im_quotejson Quote a JSON string. im_rest_authenticate Determine the authenticated user im_rest_call Handler for all REST calls im_rest_call_delete Handler for DELETE rest calls im_rest_call_get Handler for GET rest calls im_rest_call_post Handler for GET rest calls im_rest_call_put Handler for PUT rest calls im_rest_cookie_auth_user_id Determine the user_id even if ns_conn doesn't work in a HTTP PUT call im_rest_debug_headers Show REST call headers im_rest_delete_object Handler for DELETE rest calls to an individual object: Update the specific object using a generic update procedure 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 This is a hack to get the content of the REST request. im_rest_get_im_categories Handler for GET rest calls on invoice items. im_rest_get_im_dynfield_attributes Handler for GET rest calls on dynfield attributes im_rest_get_im_hour_intervals Handler for GET rest calls on timesheet hour intervals im_rest_get_im_hours Handler for GET rest calls on timesheet hours im_rest_get_im_indicator_result_interval Handler for GET rest calls on indicator results im_rest_get_im_invoice_items Handler for GET rest calls on invoice items. im_rest_get_im_timesheet_task_dependencies Handler for GET rest calls on task dependencies im_rest_get_object_type Handler for GET rest calls on a whole object type - mapped to queries on the specified object type 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_header_extra_stuff Returns a number of HTML header code in order to make the REST interface create reasonable HTML pages. im_rest_normalize_timestamp Reformat JS 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_subtypes Returns a list of all object types equal or below rest_otype (including rest_otype). im_rest_object_type_update_sql Updates all the object's tables with the information from the hash array. im_rest_page The user has requested /intranet-rest/index or /intranet-rest/data-source/* 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_post_object Handler for POST rest calls to an individual object: Update the specific object using a generic update procedure im_rest_post_object_im_hour Handler for POST calls on particular im_hour objects. im_rest_post_object_im_hour_interval Handler for POST calls on particular im_hour_interval objects. im_rest_post_object_type Handler for POST rest calls to an object type - create a new object. im_rest_post_object_type_im_biz_object_member Create a new object and return the object_id. im_rest_post_object_type_im_company Create a new Company and return the company_id. im_rest_post_object_type_im_company_employee_rel Create a new object and return the object_id. im_rest_post_object_type_im_hour Create a new Timesheet Hour line and return the item_id. im_rest_post_object_type_im_hour_interval Create a new Timesheet Hour line and return the item_id. im_rest_post_object_type_im_invoice Create a new Financial Document and return the task_id. im_rest_post_object_type_im_invoice_item Create a new Financial Document line and return the item_id. im_rest_post_object_type_im_key_account_rel Create a new object and return the object_id. im_rest_post_object_type_im_note Handler for POST calls on particular im_note objects. im_rest_post_object_type_im_project Create a new object and return the object_id. im_rest_post_object_type_im_sencha_column_config Handler for POST calls on particular im_sencha_column_config objects. im_rest_post_object_type_im_sencha_preference Handler for POST calls on particular im_sencha_preference objects. im_rest_post_object_type_im_ticket Create a new object and return its object_id im_rest_post_object_type_im_ticket_ticket_rel Create a new object and return the object_id. im_rest_post_object_type_im_timesheet_task Create a new object and return its object_id im_rest_post_object_type_im_timesheet_task_dependency Create a new task dependency and return the id. im_rest_post_object_type_im_trans_invoice Create a new object and return the object_id im_rest_post_object_type_im_trans_task Create a new object and return the object_id. im_rest_post_object_type_im_user_absence Create a new User Absence and return the company_id. im_rest_post_object_type_membership_rel Create a new object and return the object_id. im_rest_post_object_type_user Create a new User object return the user_id. 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_predecessors Update the resource predecessors to the task im_rest_project_task_tree_update Update a task coming from TreeStore im_rest_system_url Returns a the system's "official" URL without trailing slash suitable to prefix all hrefs used for the JSON format. im_rest_valid_sql Returns 1 if "where_clause" is a valid where_clause or 0 otherwise. im_rest_validate_call Performs a REST call and returns the results. im_rest_validate_list Checks permissions to "list" on all object types im_rest_validate_projects Checks permissions on ]po[ projects im_rest_version Returns the current server version of the REST interface. 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/postgresql/intranet-rest-create.sql sql/postgresql/intranet-rest-drop.sql
www/ | |
auto-login.adp | |
auto-login.tcl | Home page for REST service, when accessing from the browser. |
data-source/ | |
auto-login-token.tcl | Provide the user with cookies and a login token |
domain-proxy.adp | |
domain-proxy.tcl | Fetches a page from www.project-open.net |
next-object-id.adp | |
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
08902 Hospitalet de Llobregat (Barcelona)
Spain
Tel Europe: +34 609 953 751
Tel US: +1 415 200 2465
Mail: info@project-open.com