REST V1 Interface Specifications

1. REST V1 Interface Specifications This document contains the specification for the REST V1 ]project-open[ Web-Services Interface

2. REST Interface Overview • 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.

3. CRUL (Create, Read, Update, List) REST Operations • “D=Delete”: Delete operations are not supported with this REST interface in the same way as deleting/“nuking” is not supported via the ]po[ WEB GUI.

4. REST Application Scenarios • The following application scenarios are supported by the ]po[ REST interface: • Project Reporting:An external applications report into ]project-open[ the creation of new projects, their financial status, and their completion degree. • Timesheet Reporting:An external application captures employee’s timesheet hours and reports them to ]project-open[. • AJAX Task Management GUI:An AJAX GUI allows users to keep track of tasks (project, milestones, timesheet tasks, translation tasks, forum tasks) assigned to the user and to mark tasks as done.

5. REST Interface Details

6. L=List Operation • Objective: Retrieve a list of objects that match certain criteria. • Implementation:A HTTP GET operation on object type resource page returns an XML structure with a list of references to object resource pages. • Request example:http://localhost/intranet-rest/im_project?format=xml&query=project_status_id=76 • Result example:<?xml version='1.0'?><object_list><object_id href="http://localhost/intranet-rest/im_project/13074">13074</object_id>...</object_list> • URL format and parameters: • URL format: http://localhost/intranet-rest/<object_type> where object_type is one of the supported REST object types. • format={xml|html}: Determines output format (see below) • limit=<integer>: Limits the number of returned objects • query=<SQL where clause>: Limits objects listed.The SQL where clause allows AND and OR conditions with the operators “=“, “<“, “>”, “<=“, “>=“, “like” and “in”.

7. R=Read Operation • Objective: Retrieve all information about one specific object. • Implementation:A HTTP GET operation on an object’s resource page returns an XML structure with a list of the object’s attributes. • Request example:http://localhost/intranet-rest/im_project/12345?format=xml • Result example:<?xml version='1.0'?><im_project> <project_name>System Specification</project_name><project_nr>2005_0027</project_nr><company_id href="http://localhost/intranet-rest/im_company/8720">8720</company_id>...(a list of ~60 attributes from the im_projects table)</im_project> • URL format and parameters: • URL format: http://localhost/intranet-rest/<object_type>/<object_id>where object_type is one of the supported REST object types and object_id is a ]po[ object of type object_type. • format={xml | html}: Determines output format (see below). • Result format: • The result document consists of a single XML tag named “object_type” containing all attributes from the object’s SQL tables”. For example, the result for the object type “im_timesheet_task” will return all columns from the table acs_objects, im_projects and im_timesheet_tasks, because im_timesheet_task is a sub-type of im_project, which in turn is a sub-type of acs_object. • The result attributes includes DynField dynamic fields and manually added database columns. • Every attribute will be returned in the format:<attribute_name>attribute_value</attribute_name>where “attribute_name” is the column in the object’s table and “attribute_value” is the value of the attribute as returned by the underlying PostgreSQL database and its default formatting. • Certain XML attributes representing references to other ]po[ objects will include an additional “href” XML attribute:href="http://192.168.140.128::8000/intranet-rest/im_company/8720" • In case an attribute name exists as a column in more then one object’s table, an undefined value is returned. Therefore, please do not create DynField or other columns with ambiguous names.

8. U=Update Operation • Objective: Update one or more attributes of an object. • Implementation:A HTTP POST operation on the object resource page updates the attributes included in the POST operation’s content XML structure. • Request example:http://localhost/intranet-rest/im_project/12345The following POST content will update the project’s “budget_hours” field:<?xml version='1.0'?><im_project><budget_hours>10000</budget_hours></im_project> • Result example:The call will return a HTTP 200 error code on success, or an error code plus an error message otherwise.The database may reject update operations because of referential integrity constraints, unique indices and other constraints. In such a case, the REST interface will return an error • URL format and update content XML structure: • URL format: http://localhost/intranet-rest/<object_type>/<object_id> where object_id is a valid object of the supported REST object_type. • The POST content may contain any of the object’s attributes, surrounded by an XML tag with the name of the object_type. In particular, the POST content may include the XML document returned by a previous R=Read operation on the object. • Certain attributes in the POST content are ignored during the update process, because they refer to ]po[ internal management mechanisms. Ignored attributes include: • “Index columns” (primary keys of an object’s tables) • Any attributes related to acs_object (creation_user, creation_date, …) • Attributes related to tree managemet (“tree_sortkey” and “max_child_sortkey”) • Attributes ending with “_cache” (representing im_project’s cached financial information)

9. C=Create Operation • Objective: Create a new object of a specified object type • Implementation:A HTTP POST operation on the object resource page creates a new object. • Request example:http://localhost/intranet-rest/im_projectThe following POST content will create a new project. For the meaning of project_type_id and project_status_id please see the data model documentation at www.project-open.org:<?xml version='1.0'?><im_project><project_name>Test Project 001</project_name><project_nr>2009_1234</project_nr><project_path>2009_1234</project_path><company_id>8773</company_id><parent_id></parent_id><project_type_id>2501</project_type_id><project_status_id>76</project_status_id></im_project> • Result example:The call will return an XML document with a 200 code on success:<?xml version='1.0'?><object_id>$rest_oid</object_id>or an HTTP error code and an error message otherwise. Please note that the creation of objects are constraint by PostgreSQL database referential integrity, unique and other constraints, which are outside of the scope of this document. • URL format and update content XML structure: • URL format: http://localhost/intranet-rest/<object_type> where object_type is a supported ]po[ REST object type. • The HTTP POST XML structure behaves the same as with the U=Update command.

10. REST Authentication • 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.

11. REST Authentication Overview THE REST API provides a choice of three different authentication mechanisms: • REST Basic HTTP Authentication:]po[ accepts standard username/password combinations via HTTP “Basic” authentication”. You can find out about a user's username either in the user's home page or in the cc_users.username field. You need to set the parameter EnableUsersUsernameP to 1 in order to tell the ]po[ GUI to show the username as part of the normal UserViewPage. • OpenACS Cookie Authentication:The standard OpenACS authentication allows you to explore the REST API interactively in HTML format. The fact that you see this page right now is due to cookie authentication. However, cookie authentication is not very useful for machine-machine communication... • REST Auto-Login Token:An auto-login token is a hashed password. To determine a user's auto-login token please visit the URL /intranet-rest/auto-login. This page will return an auto-login token for a user who has authenticated via Cookie or Basic Auth.

12. BASIC HTTP Authentication • 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 --auth-no-challenge http://192.168.140.128:8000/intranet-rest/im_project • 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>

13. OpenACS Cookie Authentication • “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.

14. REST Auto-Login Token Authentication • 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: • User ID: 624 • Name: System Administrator • Username: sysadmin • Auto-Login Token:41909DE9FEB3B556C6C7266F246E03A43403E852 • 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

15. REST Technical Specs

16. Design Goals • Completeness:Expose all ]po[ objects as a Web service, not just a few. Provide the means for external applications to actually replace ]po[. • REST standards:Follow the best practices or REST interfaces as defined by Roy Fielding implemented by important examples of REST interfaces. • Open for all Users:Use tight permissions to allow all users to use the REST interface, not just for system administrators. Show restricted users only the appropriate objects and restrict the update operations to objects where the user have write permissions.

17. REST Resources for Objects and Object Types • The REST package is available at the URL:http://<your_server>/intranet-rest/. • An “Object Type Resource” allows for operations on an object type, including L=List objects with certain characteristics and C=Create new objects of the type:http://<your_server>/intranet-rest/<object_type> • An “Object Resource” allows to R=Read the attributes of a specific object or to U=Update the object’s attributes:http://<your_server>/intranet-rest/<object_type>/<object_id>

18. Encoding & Formatting • URL variables are supposed to be encoded using “%” URL encoding according to RFC 1738 (http://www.ietf.org/rfc/rfc1738.txt) • All documents returned by the REST interface are available in the formats “xml” and “html”. The URL parameter format={xml|html} determines output format. “Html” is default for cookie authentication (using the REST via a browser). “Xml” is the default otherwise. • All XML documents sent and received are encoded in UTF-8 format. • HTML documents are only designed to be human readable, no specific encoding is defined.

19. Error Messages and Return Status Error Status • 200 OK: Success! • 304 Not Modified: There was no new data to return. • 400 Bad Request: The request was invalid. An accompanying error message will explain why. • 401 Not Authorized: Authentication credentials were missing or incorrect. • 403 Forbidden: The request is understood, but it has been refused. An accompanying error message will explain why. • 404 Not Found: The URI requested is invalid or the resource requested, for example a non-existing project. • 406 Not Acceptable: Returned by the Search API when an invalid format is specified in the request. • 500 Internal Server Error: Something is broken. Please post to the ]po[ “Open Discussions” forum. • 502 Bad Gateway: ]project-open[ is probably down. • 503 Service Unavailable: ]project-open[ is up, but overloaded with requests. Try again later. 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>

20. Supported ]po[ Object Types • 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: • group • im_biz_object_member • im_company • im_company_employee_rel • im_conf_item • im_conf_item_project_rel • im_cost_center • im_expense • im_expense_bundle • im_forum_topic • im_fs_file • im_invoice • im_key_account_rel • im_material • im_office • im_profile • im_project • im_release_item • im_rest_object_type • im_ticket • im_ticket_queue • im_ticket_ticket_rel • im_timesheet_invoice • im_timesheet_task • im_trans_invoice • im_trans_task • im_user_absence • membership_rel • party • person • relationship • user

21. ToDo

22. ToDo’s • Specify which projects exactly are returned with the im_project GET request (what about sub-projects and the im_timesheet_tasks below a project that a user can see)? • Implement Invoice Create operations, including Invoice Lines and relating the invoice to a project. • Implement the log hours application scenarios (how to treat im_hours, which is not an object…)? • Perform a complete white box security check • Implement a HTML GUI for creating and updating object interactively