Skip Headers
Oracle® Fusion Middleware Web Service Developer's Guide for Oracle WebCenter Interaction
10g Release 4 (10.3.3.0.0)
Part Number E14109-02
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

5 Oracle WebCenter Interaction REST APIs

Oracle WebCenter Interaction REST APIs allow remote web services to post documents to the portal Directory, update Community membership, and post stories to portal user's activity stream through simple HTTP requests.

REST stands for Representational State Transfer and is a simple way of providing APIs over HTTP. The basic principles of REST are:

These APIs do not support the full REST range (i.e. CRUD), and handle a small amount of functionality. The following REST APIs are available:

Note:

The Oracle WebCenter Interaction REST APIs are protected by Oracle WebCenter Interaction security. Access is restricted to portal users by login token verification or basic authentication. For details, see Configuring Web Services that Use Oracle WebCenter Interaction REST APIs.

Using the Oracle WebCenter Interaction Directory REST API

To add a new document to a the portal Directory, send a POST request containing the necessary data to the portal URL.

The post must be of content-type “application/json” and use the following syntax:

POST http://host/portal/server.pt/api/v1/kd/{FOLDER ID}

{
  "document": {
    "name": "NAME",
    "description": "DESCRIPTION",
    "datasourceid": "DATA SOURCE ID",
    "contenturl": "CONTENT URL"
  }
}

For increased security, all JSON used in the API must be comment filtered. The JSON data should be wrapped in /* */ for any JSON, either in the API request or response. In addition, all JSON output will be wrapped in a plain { } block so that it can't be used directly in a script src tag.

Variable Description

FOLDER ID

The ID of the Directory folder to access. The folder must already exist in the portal. If you do not know the folder ID, there are two ways to retrieve one:

NAME

The name of the document to be displayed in the Directory.

DESCRIPTION

The description of the document to be displayed in the Directory.

DATA SOURCE ID

The Content Source ID for the document. The ID must be a valid Content Source configured in the portal. For example, the World Wide Web Content Source is ID 104.

CONTENT URL

The full file path to the document.

Note:

The Oracle WebCenter Interaction REST APIs are protected by Oracle WebCenter Interaction security. Access is restricted to portal users by login token verification or basic authentication. For details, see Configuring Web Services that Use Oracle WebCenter Interaction REST APIs.

The response will include one of the following HTTP codes:

The response body includes the new object ID and the path to the folder and uses the following syntax:

{
  "document": {
    "name": "Document name",
    "objectid": "2143",
    "folderid": "1983",
    "folderpath": "\Knowledge Directory\test folder\submits"
  }
}

To view a complete implementation of this API, see the Submit to Knowledge Directory portlet included with the Oracle WebCenter Interaction installation (in the image service under /plumtree/portal/private/kdsubmit/).

Using the Oracle WebCenter Interaction User REST API

To add or remove a user from a Community, send a POST request containing the necessary data to the portal URL.

The post must be of content-type “application/json” and use the following syntax:

POST http://host/portal/server.pt/api/v1/user/current

{
  "user": {
    "joincommunityid": "COMMUNITY ID",
    "leavecommunityid": "COMMUNITY ID"
  }
}

For increased security, all JSON used in the API must be comment filtered. The JSON data should be wrapped in /* */ for any JSON, either in the API request or response. In addition, all JSON output will be wrapped in a plain { } block so that it can't be used directly in a script src tag. This API currently only supports the special keyword "current" for the user identifier, meaning the current user. This API cannot be used to access users other than the currently logged in user.

Variable Description

COMMUNITY ID

The ID of the Community to join or unsubscribe.

Note:

The Oracle WebCenter Interaction REST APIs are protected by Oracle WebCenter Interaction security. Access is restricted to portal users by login token verification or basic authentication. For details, see Configuring Web Services that Use Oracle WebCenter Interaction REST APIs.

The response will include one of the following HTTP codes:

The response will be in JSON. The response body uses the following syntax:

{
  "user": {
    "joincommunityid": "COMMUNITY ID",
    "leavecommunityid": "COMMUNITY ID"
  }
}

To view a complete implementation of this API, see the Join Communities flyout included with the Oracle WebCenter Interaction installation (in the image service under /plumtree/portal/private/joincommunities/).

Using the Oracle WebCenter Interaction Activity Stream API

To add a new story to a user's Activity Stream, send a POST request containing the necessary data to the story server URL.

The post must use the following syntax:

POST http://${STORY_SERVER_URL}/api/story/v1/activities/${USER_ID_TYPE}/${USER_ID_PREFIX}/${USER_ID_SUFFIX}

<soc:activity xmlns:soc="http://social.bea.com/activity">
  <body><![CDATA[${EVENT}]]></body>
</soc:activity>
Variable Description

STORY_SERVER_URL

The URL to the story server, typically, %HOSTNAME%:21030/activityservice.

USER_ID_TYPE

The type of user identifier that follows; acceptable values are: username (login name), UUID, & ID (portal object integer ID). XXXXX Note: These strings must be lowercase. XXXXX

The identifier of the user that the story is about; in the case of domain qualified names, this is the domain name. (For example, bea\jking will be represented as .../username/bea/jking in the post URL.)

USER_ID_PREFIX

USER_ID_SUFFIX

(Optional.) In the case of domain qualified names, this is the username; omitted in all other cases.

EVENT

The story itself (the CDATA envelope is optional if the story does not include any markup).

Note:

The Activity Stream API is protected by Oracle WebCenter Interaction security. Access is restricted to portal users by login token verification or basic authentication. For details, see XXX404 not found error in the html to tsk_ali_activitystreamapi_configuring.dita XXX.

The response will include one of the following HTTP codes:

The response body uses the following syntax:

<soc:activity xmlns:soc="http://social.bea.com/activity">
    <body>post content</body>
    <userId>4258</userId>
    <senderFullName>Joe King</senderName>
    <senderIP>10.60.28.195</senderIP>
    <userUUID>E523D1A7-475E-0B4D-76CA-6F9001480000</userUUID>
    <userFullName>Joe King</userFullName>
    <version>v1</version>
</soc:activity>

The post can be implemented in many ways, as shown in the examples that follow.

HTML/JavaScript Example

<script type="text/javascript">
        // Get the gatewayed URL - This will give us authentication and prevent cross domain POST errors.
        var activitystreamBaseURL = "<pt:common.url xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/' pt:href='http://bfraser03.bea.com:21030/activityservice/api/story/v1/activities/'/>";
        // Get the sender's full name.
        var senderName = "<pt:common.userinfo pt:info='FullName' xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>";
    
        var portalURL = "http://bfraser03.bea.com:8080/portal/server.pt";
 
        function sendStory() {
                var to = document.getElementById('to').value;
                var message = linkedName() + ' wrote: '
                                + document.getElementById('message').value;
 
                doRestCall(
                                'POST',
                                activitystreamBaseURL + 'username/' + to,
                                '<?xml version="1.0" encoding="UTF-8"?>'
                                                + '<soc:activity xmlns:soc="http://social.bea.com/activity">'
                                                + '<body><![CDATA[' + message + ']]></body>'
                                                + '</soc:activity>');
        }
 
        function doRestCall(requestType, postURL, xml) {
                var xmlhttp;
                // Get the XMLHttpRequest object -- needs to work for IE and non-IE browsers
                if (window.XMLHttpRequest) {
                        xmlhttp = new XMLHttpRequest();
                } else if (window.ActiveXObject) {
                        xmlhttp = new ActiveXObject("Microsoft.XMLHttp");
                }
                // Set the callback as an anonymous funcion
                xmlhttp.onreadystatechange = function() {
                        if (xmlhttp.readyState == 4) {
                                var str = '<div>';
                                // We should get 201 CREATED on successful POST
                                if (xmlhttp.status == 201) {
                                        str = str + 'Message sent!';
                                } else {
                                        str = str + 'ERROR: ' + xmlhttp.status + '</div><div>'
                                                        + xmlhttp.responseText + '</div>';
                                }
                                document.getElementById('output').innerHTML = str;
                        }
                }
                xmlhttp.open(requestType, postURL, true);
                xmlhttp.setRequestHeader("Content-Type", "text/xml");
                xmlhttp.send(xml);
        }
 
        function linkedName() {
                // This function returns viewing userÕs name hyperlinked to their homepage.
                var nameurl = senderName.replace(" ", "_");
                nameurl = nameurl.toLowerCase();
                var link = '<a href="' + portalURL + '/user/' + nameurl + '">'
                                + senderName + '</a>';
                return link;
        }
</script>
<div>Send a message to: <input id="to" type="text" size="30"/></div>
<div>Message: <input id="message" type="text" size="40" /></div>
<div><a href="#" onclick="sendStory();"> send it! </a></div>
<div id="output"></div>

Java Example

The Java example below sends the message “Check out the <a href=\"http://www.bea.com\">BEA</a> home page!”.

ActivityStreamUtil.java

package bea.sample.activitystream;
 
import java.io.UnsupportedEncodingException;
 
import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.auth.AuthScope;
import org.apache.commons.httpclient.methods.*;
 
public class ActivityStreamUtil {
 
        public static HttpClient CreateAuthenticatedClient(String username,
                        String password) {
                HttpClient client = new HttpClient();
 
                // This is promiscuous be careful
                client.getState().setCredentials(AuthScope.ANY,
                                new UsernamePasswordCredentials(username, password));
                // Send credentials with request without waiting for challenge
                client.getParams().setAuthenticationPreemptive(true);
 
                return client;
        }
 
        public static PostMethod CreateActivityStreamPost(String url, String body) {
                PostMethod postMethod = new PostMethod(url);
                RequestEntity requestEntity = null;
                try {
                        requestEntity = new StringRequestEntity("<activity><body><![CDATA["
                                        + body + "]]></body></activity>", "text/xml", "UTF-8");
                } catch (UnsupportedEncodingException e) {
                        e.printStackTrace();
                }
                postMethod.setRequestEntity(requestEntity);
                return postMethod;
        }
}

ActivityStreamPost.java

package bea.sample.activitystream;
 
import java.io.IOException;
 
import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.methods.PostMethod;
 
public class ActivityStreamPost {
        public static final String ACT_USERNAME = "username";
        public static final String ACT_ID = "id";
        public static final String ACT_UUID = "uuid";
 
        public static void main(String[] args) {
                // Post to the guest user by name from the administrator account.
                String host = "localhost:21030";
                String userIDType = ACT_USERNAME;
                String userID = "guest";
                String username = "administrator";
                String password = "admin";
                String url = "http://" + host
                                + "/activityservice/api/story/v1/activities/" + userIDType
                                + "/" + userID;
                String message = "Check out the <a href=\"http://www.bea.com\">BEA</a> home page!";
                HttpClient client = ActivityStreamUtil.CreateAuthenticatedClient(
                                username, password);
                PostMethod post = ActivityStreamUtil.CreateActivityStreamPost(url,
                                message);
                try {
                        int status = client.executeMethod(post);
                        if (status == HttpStatus.SC_CREATED) {
                                System.out.println("Post successful");
                                System.out.println(post.getResponseBodyAsString());
                        } else {
                                System.err.println("Method failed: " + post.getStatusLine());
                        }
                } catch (HttpException e) {
                        System.err.println("Fatal protocol violation: " + e.getMessage());
                        e.printStackTrace();
                } catch (IOException e) {
                        System.err.println("Fatal transport error: " + e.getMessage());
                        e.printStackTrace();
                } finally {
                        post.releaseConnection();
                }
        }
}

.NET Example

The .NET (C#) example below sends the message 'Greetings from .NET!”.

using System;
using System.Collections.Generic;
using System.Text;
using System.Net;
using System.IO;
 
namespace ActivityServiceTest
{
    class Program
    {
        static void Main(string[] args)
        {
            string url = "http://localhost:8090/activityservice/api/story/v1/activities/username/bea/nsuravar";
            string username = "test";
            string password = "plumtree";
            string data = "<soc:activity xmlns:soc=\"http://social.bea.com/activity\"><body>Greetings from .NET!</body></soc:activity>";
 
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            request.Method = "POST";
            request.Credentials = new NetworkCredential(username, password);
            request.ContentLength = data.Length;
            request.KeepAlive = false;
            System.Net.ServicePointManager.Expect100Continue = false;
            Uri uri = new Uri(url);
 
            NetworkCredential Credentials = request.Credentials.GetCredential(uri, "Basic");
            
            request.ContentType = "text/xml;charset=UTF-8";
            
            if (Credentials != null)
            {
                byte[] credentialBuffer = new UTF8Encoding().GetBytes(
                    Credentials.UserName + ":" +
                    Credentials.Password);
                request.Headers["Authorization"] =
                    "Basic " + Convert.ToBase64String(credentialBuffer);
            }
         
            StreamWriter writer = new StreamWriter(request.GetRequestStream());
            writer.Write(data);
            writer.Close();
             
            try
            {
                WebResponse response = request.GetResponse();
 
                 byte[] ByteArray = response.Headers.ToByteArray();
                using (StreamReader reader = new StreamReader(response.GetResponseStream()))
                {
                    while (reader.Peek() != -1)
                    {
                        Console.WriteLine(reader.ReadLine());
                     }
                }
            }
            catch (Exception ex)
            {
                Console.Write(ex.ToString());
            }
        }
    }
}

Configuring Web Services that Use Oracle WebCenter Interaction REST APIs

To send the portal login token or basic authentication information to a remote application that uses Oracle WebCenter Interaction REST APIs, register the remote application as a Web Service in the portal.

To use a Oracle WebCenter Interaction REST API, a remote application must have access to the portal login token or a portal user's basic authentication information. To send this information to the remote application, create a Web Service in the portal for the remote application and configure the following settings. (For detailed information on Web Service configuration settings, see the portal online help.)

Note:

To use the Activity Stream API from a remote web service, the Remote Portlet Service must be installed and enabled. The Remote Portlet Service and Activity Stream sample portlets are included in the activityservice.pte file provided with the Oracle WebCenter Interaction installation package. For details on installation and configuration, see the Installation Guide for Oracle WebCenter Interaction and the Administrator Guide for Oracle WebCenter Interaction.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us