project-open[ REST V1 Interface Specifications

righteousgaggleΔιαχείριση Δεδομένων

31 Ιαν 2013 (πριν από 4 χρόνια και 6 μήνες)

133 εμφανίσεις

REST V1 Interface Specifications

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


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.

HTTP “GET”

Operation

HTTP “POST”

Operation

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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
5

REST Interface Details



]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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”.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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

th
e
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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_projec
t/12345

The 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)


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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_projec
t

The 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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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>


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
15

REST Technical Specs



]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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>


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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.


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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>


]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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




]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
21

ToDo



]project
-
opem[ 2008
, Rollout Methodology / Frank Bergmann /
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