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‚ÄĚ|
Lists all object
of that object type.
Creates a new instance
of the object type.
Retrieves all fields
of the specified object
Updates the specified
‚Äú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
sql/postgresql/intranet-rest-create.sql sql/postgresql/intranet-rest-drop.sql sql/postgresql/upgrade/upgrade-22.214.171.124.2-126.96.36.199.3.sql sql/postgresql/upgrade/upgrade-188.8.131.52.0-184.108.40.206.1.sql
|auto-login.tcl||Home page for REST service, when accessing from the browser.|
|domain-proxy.tcl||Fetches a page from www.project-open.net|
|project-task-tree.json.tcl||Returns a JSON tree structure suitable for batch-loading a project TreeStore|