ODS Controllers

Overview

ODS Controllers enable programmatic manipulation of ODS based Data Spaces via RESTful Web Services.

Access point

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.

Authentication

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.

Password Hash Authentication

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.

Password Hash Authentication Example

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

OAuth

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:

  1. client uses request_token to get a token/secret pair for establishing session using consumer token
  2. client asks OAuth server to authorize the token from step 1
  3. using authorized token from step 1, client asks OAuth server for authentication token
  4. with authentication token from step 3, clients can access instance data associated with the consumer token from step 1

OAuth Examples

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.

Response format

The following Response format are supported by the ODS Controllers implementation:

OperationFormatExampleDescription
IUD operations On success; On failureOn success: <result>
  <code>NNN</code>
  <message>human readable explanation if applicable</message>
</result>

On failure: <failed>
  <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.

API methods

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.

Framework Controllers

ControllerDemo LinksDescription
user.register (
  name varchar,
  password varchar
  email varchar
)
ExampleRegisters new user.
user.authenticate (
  user_name varchar,
  password_hash varchar
)
ExampleAuthenticates existing user.
user.update (user_info any) Updates user's data.
user.password_change (new_password varchar)ExampleChanges user password.
user.delete (name varchar)ExampleDeletes user.
user.enable (name varchar)ExampleEnables user.
user.disable (name varchar)ExampleDisables user.
user.get (name varchar)ExampleGets user data.
user.search (pattern varchar)ExamplePerforms 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 ()ExampleGets 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
)
ExampleCreates 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.

ODS Data Spaces Controllers

The following ODS Data Spaces offer a variety of application specific controllers:

ODS Data SpaceControllersProgrammers GuideDescription
BriefcaseList Briefcase Data Space collection of controllers covers all activities for managing user resources.
WeblogListView Weblog Data Space collection of controllers includes manipulation of user weblog posts, hyperlinking tags, etc.
AddressbookListView AdressBook? Data Space collection of controllers covers different ways of managing user's contacts, personal data, annotations and many others.
BookmarksListView 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.
PollsListView Polls Data Space collection of controllers offers a variety of commands for creating., editing, deleting users polls.
Calendar ListView Calendar Data Space collection of controllers covers organizing user's Calendar events and tags, import and export, managing subscriptions and publications.
Feed ManagerListView Feed Manager Data Space collection of controllers covers managing user's subscriptions data, import and export, changing specific feed's details, and many others.
WebmailListView Webmail Data Space collection of controllers covers managing user's webmail data.
DiscussionListView Discussions Data Space collection of controllers covers managing discussions groups and posts data.
GalleryList Gallery Data Space collection of controllers covers managing user's own galleries' images and settings.
WikiList Wiki Data Space collection of controllers covers managing user's wiki articles details, upstreaming and many others.
MessengerList MessengerData? Space collection of controllers covers managing user's messages.

References

CategoryODS CategoryVirtuoso