• Topic
  • Discussion
    • ODS.VirtuosoOdsControllers(1.1) -- DAVWikiAdmin? , 2017-06-13 06:02:42 Edit
    [TXT]
    [PLAIN]
    [DOCBOOK]
    WebDAV System Administrator 2017-06-13 06:02:42

    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:

    Operation Format Example Description
    IUD operations On success; On failure On 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

    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.

    ODS Data Spaces Controllers

    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.

    References

    CategoryODS CategoryVirtuoso