ODS Controllers enable programmatic manipulation of ODS based Data Spaces via RESTful Web Services.
The API can be accessed via REST using http://host:port/ods/api/[method].
Parameters specific to each method are given as URL parameters if using GET, as www-url-encoded or multipart/form-data if using POST.
The API can be accessed via UI page using http://host:port/ods/oauth_test.vsp.
Most API calls which modify data, i.e., CRUD operations, need authentication; thus the requests need to be authenticated using OAuth, or session + password hashes. The user account used to authenticate in either case MUST have relevant privileges to a given ODS data space. This is done by granting owner or author level membership to the given data space.
When authenticating via password hashes parameters 'user_name' and 'password_hash' need to be specified.
The password hash uses the sha1 digest algorithm and includes both the user name and the password.
To authenticate user demo with password foobar the sha1 digest of the term demofoobar needs to be provided.
This can be created via openssl or any sha1 tool:
# echo -n "demofoobar" | openssl dgst -sha1 # echo -n "demofoobar" | sha1sum
The user account for authentication must have OAuth tokens generated via ODS -> Settings -> OAuth keys. This UI provides a list of all applications to which the user has access (i.e., he/she is member or owner). If an instance needs to be accessed with OAuth, user simply selects the instance from the list and clicks 'generate keys'. The generated consumer key & token will be associated to the active ODS user account and selected application instance.
Once a consumer token is available, the sequence below must be done in order to establish an authorized session:
To demonstrate the above, we supply a simple client written in VSP.
Also there are available Examples of sample session recorded with the client above.
The following Response format are supported by the ODS Controllers implementation:
| Operation | Format | Example | Description |
|---|---|---|---|
| IUD operations | On success; On failure | On success: <code>NNN</code> <message>human readable explanation if applicable</message> </result> On failure: <code>NNN</code> <message>human readable explanation</message> </failed> | The IUD methods return an XML response with code & message format are On success and On failure |
| Search (get) | The search methods returns results in RDF format according to FOAF, SIOC and SIOC types module ontology. See ODS RDF model. |
All APIs are acting on behalf of the user who established authentication, i.e., the user which is authorized. The APIs where user is subject of removal or freeze as well as registration the user name is passed as parameter. Therefore user.register, user.delete would need user name as input parameter where user.update, instance.create will use the user from authentication information.
| Controller | Demo Links | Description |
|---|---|---|
| user.register ( name varchar, password varchar email varchar ) | Example | Registers new user. |
| user.authenticate ( user_name varchar, password_hash varchar ) | Example | Authenticates existing user. |
| user.update (user_info any) | Updates user's data. | |
| user.password_change (new_password varchar) | Example | Changes user password. |
| user.delete (name varchar) | Example | Deletes user. |
| user.enable (name varchar) | Example | Enables user. |
| user.disable (name varchar) | Example | Disables user. |
| user.get (name varchar) | Example | Gets user data. |
| user.search (pattern varchar) | Example | Performs search for user by given pattern. |
| user.invite ( friends_email varchar, custom_message varchar default ) | Example | Invites user |
| user.invitation ( invitation_id varchar, approve int ) | Gets user invitation details. | |
| user.invitations.get () | Example | Gets all user's invitations. |
| user.relation_terminate (friend varchar) | Terminates a relation with user. | |
| user.tagging_rules.add ( rulelist_name varchar, rules any, is_public int default 1 ) | Adds tagging rule. | |
| user.tagging_rules.delete (rulelist_name varchar) | Deletes tagging rule. | |
| user.tagging_rules.update ( rulelist_name varchar, rules any ) | Updates tagging rule. | |
| user.hyperlinking_rules.add (rules any) | Adds user hyperlinking rule. | |
| user.hyperlinking_rules.update (rules any) | Updates user hyperlinking rule. | |
| user.hyperlinking_rules.delete (rules any) | Deletes user hyperlinking rule. | |
| user.annotation.add ( claimIri varchar, claimRelation varchar, claimValue varchar ) | Adds user annotation. | |
| user.annotation.delete ( claimIri varchar, claimRelation varchar, claimValue varchar ) | Deletes user annotation. | |
| instance.create ( type varchar, name varchar, description varchar, model int, public int ) | Example | Creates ODS Dataspace instance. Its type can be: * AddressBook? * Bookmark * Calendar * Community * IM (Messenger) * Polls * WEBLOG2 (Weblog) * eCRM * eNews2 * oDrive (Briefcase) * oGallery * oMail (Webmail) * oWiki |
| instance.update ( inst_id int, name varchar, description varchar, model int, public int ) | Example | Updates instance's details. |
| instance.delete (inst_id int) | Deletes existing instance. | |
| instance.freeze (name varchar) | Example | Freeze existing instance. Its owner is no more able to manage the instance. |
| instance.unfreeze (name varchar) | Example | Unfreeze existing instance. Its owner is then enabled to manage the instance. |
| instance.join (inst_id int) | Example | Joins user to existing instance. |
| instance.disjoin (inst_id int) | Example | Dis-joins user to an existing instance he/she is member of. |
| instance.join_approve ( inst_id int, uname varchar ) | Performs instance join approve. | |
| instance.notification.services (in inst_id integer) | Shows instance notification services details. | |
| instance.notification.set ( inst_id int, services any ) | Sets instance notification data. | |
| instance.notification.cancel ( inst_id int, services any ) | Cancels instance notification services. | |
| instance.notification.log (inst_id int) | Shows instance notification log. | |
| instance.get (inst_id int) | Gets instance's details. | |
| instance.get.id (instanceName varchar) | Example | Returns instance name by given instance id. |
| site.search ( pattern varchar, options any ) | Executes search over the ODS Data space data by given pattern. |
The following ODS Data Spaces offer a variety of application specific controllers:
| ODS Data Space | Controllers | Programmers Guide | Description |
|---|---|---|---|
| Briefcase | List | Briefcase Data Space collection of controllers covers all activities for managing user resources. | |
| Weblog | List | View | Weblog Data Space collection of controllers includes manipulation of user weblog posts, hyperlinking tags, etc. |
| Addressbook | List | View | AdressBook? Data Space collection of controllers covers different ways of managing user's contacts, personal data, annotations and many others. |
| Bookmarks | List | View | Bookmarks Data Space collection includes a rich number of controllers for managing user's bookmarks details, organizing the collected data by folders, manage sharing options and many others. |
| Polls | List | View | Polls Data Space collection of controllers offers a variety of commands for creating., editing, deleting users polls. |
| Calendar | List | View | Calendar Data Space collection of controllers covers organizing user's Calendar events and tags, import and export, managing subscriptions and publications. |
| Feed Manager | List | View | Feed Manager Data Space collection of controllers covers managing user's subscriptions data, import and export, changing specific feed's details, and many others. |
| Webmail | List | View | Webmail Data Space collection of controllers covers managing user's webmail data. |
| Discussion | List | View | Discussions Data Space collection of controllers covers managing discussions groups and posts data. |
| Gallery | List | Gallery Data Space collection of controllers covers managing user's own galleries' images and settings. | |
| Wiki | List | Wiki Data Space collection of controllers covers managing user's wiki articles details, upstreaming and many others. | |
| Messenger | List | MessengerData? Space collection of controllers covers managing user's messages. |