Creating Oracle Beehive RESTful Web Services Clients


Note:

The samples featured on this page work only for Oracle Beehive Release 2 (2.0.1.0)

This page explains how to perform various tasks, such as authentication and retrieving objects from Oracle Beehive, with Oracle Beehive RESTful Web services. It also provides source code in various programming languages that demonstrate how to do these tasks. It covers the following topics:

Authenticating

The example code in this guide uses BASIC authentication and generally sends the authentication request with each call to Oracle Beehive RESTful Web services. This is done for simplicity.

Alternatively, you may send the authentication information with the first call to the server, then retain the cookie returned in the response for subsequent calls. This is more efficient as the user does not need to be authenticated with each call, especially in the case of an Oracle Beehive server synchronized with an LDAP directory. This approach also enables you to remove references to the password from the client as soon as the first call has been made.

This approach of using a cookie requires you to handle inactivity timeouts of the authenticated session. Do this by regularly looking for the 403 Forbidden HTTP status code from the server. When your client encounters this status code, prompt the user again for the password.

For BASIC authentication, set the authorization HTTP header to the Base64-encoded value of the username and password in the format username : password. This translates to an HTTP call similar to the following:

GET /my/user HTTP/1.0
Host: BeehiveServer.oracle.com
Authorization: Basic QWxhZGRpbjpvcGVuITJlc2FtZQ==

The following examples demonstrate how to authenticate a user and output some of his or her information. These examples first call the /my/user resource. This resource is a good place to start since it returns a lot of information about the logged in user, which you can use in later calls.

Table 1-1 BDK Authentication Examples

Platform Requirements Source Code Files

C#

Refer to "C# BDK Clients"

Refer to "C# BDK Examples"

Flex

Refer to "Adobe Flex Clients"

Refer to "Adobe Flex Samples"

Java

Follow the steps described in "Setup with Third Party APIs"

Refer to "Java BDK Examples"

JavaScript

Refer to "JavaScript BDK Clients"

Refer to "JavaScript Samples"

Securing POST, PUT, and DELETE Method Calls

All calls to POST, PUT, and DELETE method calls require an anti-CSRF token. This anti-CSRF token guards against cross-site request forgery (CSRF) attacks.

Follow these steps to retrieve and specify this anti-CSRF token whenever you call a POST, PUT, and DELETE method.

Step 1   Retrieve the anti-CSRF token

This step assumes you already successfully logged in with the POST method /session/login

Retrieve the anti-CSRF token with the GET method /session/anticsrf:

GET /comb/v1/d/session/anticsrf
Step 2   URL encode the anti-CSRF token

Convert the anti-CSRF token to the application/x-www-form-urlencoded MIME format so that the anti-CSRF token is valid as a parameter in a HTTP method call. The anti-CSRF token frequently contains an equal sign ( =). To use the anti-CSRF token in URIs with characters like this, you must URL encode the token.

Most programming languages and environment have built-in operations for URL encoding strings. The following are suggested utilities:

Step 3   Specify the URL encoded anti-CSRF token in the HTTP method call

In the HTTP method call, set the parameter anticsrf to the URL encoded anti-CSRF token. For example, the following method demonstrates how to call the Read Batch method, /afrh/read. (This method will be used in the next section, "Listing Artifact Identifiers".)

POST /comb/v1/d/afrh/read?anticsrf=
                                         kp3PZtMeXK0%3D
                                      

Listing Artifact Identifiers

Each entity in Oracle Beehive can be uniquely identified by its enterprise ID, which has the following form:

7597:1CBE:enpr:CC2F84E87F334B0AAE62BA7F51AABC82000000000000

The four letter acronym enpr designates the type of entity this identifier represents; in this case, this is the identifier of an enterprise entity.

You typically obtain these identifiers by calling the /list resource or from an element listed within another entity. The examples in this section describe these techniques.

Step 1   Retrieve the logged in user's information

Refer to the examples in the section "Authenticating". Many of the examples in this guide use utility or helper classes to make them easier to follow.

Step 2   Retrieve the logged in user's personal workspace information

Retrieve the logged in user's PersonalWorkspace identifier from the previous step. With this identifier, retrieve the PersonalWorkspace entity by calling the following resource:

/wspr/
                                       {id}
                                    

{id} is the PersonalWorkspace identifier retrieved from the previous step.

Step 3   Retrieve the names of the folders in the PersonalWorkspace entity

The call to /wspr/ {id} retrieves a list of folders of various types. From this list, retrieve the folders of the generic type HeterogeneousFolder. One way to do this is to make several calls to the resource /wspr/ {id} , where {id} is the identifier of a folder you are interested in.

However, you can achieve this more efficiently by calling the /read resource. This involves using a POST HTTP method and creating a BeeIdList entity that contains a list of folder identifiers you want to retrieve.

Construct the BeeIdList that contains all identifiers of those elements of type HeterogeneousFolder. Post the BeeIdList to the /afrh/read resource. The server responds with a BeeArray entity that contains a list of the returned elements from the call. (Remember to specify the anti-CSRF token as described in "Securing POST, PUT, and DELETE Method Calls".)

The following examples demonstrate how to list the folders of type HeterogeneousFolder of the current, logged in user:

Table 1-2 BDK Listing Artifact Identifiers Examples

Platform Requirements Source Code Files

C#

Refer to "C# BDK Clients"

Refer to "C# BDK Examples"

Flex

Refer to "Adobe Flex Clients"

Refer to "Adobe Flex Samples"

Java

Follow the steps described in "Setup with Third Party APIs". The logged in user must have at least one team workspace.

Refer to "Java BDK Examples"

JavaScript

Refer to "JavaScript BDK Clients"

Refer to "JavaScript Samples"

Creating Simple Objects

The examples in this section describe how to create a TeamWorkspace entity. This involves specifying the team workspace's name, description, and team workspace template and calling a POST method with a creator and updater entity.

Step 1   Retrieve TeamWorkspaceTemplate

Retrieve the information of the logged in user with /my/user.

Call the POST method /ttws/list?parent= {EID of parent scope of the logged in user} :

/ttws/list?parent=7597:1CBE:enpr:CC2F84E87F334B0AAE62BA7F51AABC82000000000000&anticsrf=kp3PZtMeXK0%3D

The resource that represents team workspaces is /ttws. The method that retrieves team workspaces is /ttws/list. To retrieve team workspaces stored in a particular scope, specify the EID of that scope in the parent parameter.

Step 2   Build the creator and updater

Create a TeamWorkspaceCreator and append a TeamWorkspaceUpdater to it. Set the name, parent scope, and template properties in the creator, then use the updater to set the description.

Step 3   Post the create request to the server

Attach the TeamWorksapceCreator to the POST HTTP method and send the request to the /wstm resource. The reply contains the newly created TeamWorkspace entity.

The following examples demonstrate how to create a TeamWorkspace entity.

Table 1-3 BDK Creating Simple Objects Examples

Platform Requirements Source Code Files

C#

Refer to "C# BDK Clients"

Refer to "C# BDK Examples"

Flex

Refer to "Adobe Flex Clients"

Refer to "Adobe Flex Samples"

Java

Follow the steps described in "Setup with Third Party APIs". The logged in user must have at least one team workspace.

Refer to "Java BDK Examples"

JavaScript

Refer to "JavaScript BDK Clients"

Refer to "JavaScript Samples"

Using Projections

Although not strictly a REST concept, Oracle Beehive RESTful Web services are heavily reliant on the concept of projections, which limit the quantity of data returned for each instance of a given type. Projections do not limit the quantity of instances returned.

For example, the call to /user/ {id} ?projection=FULL retrieves the OrganizationUser with the identifier specified by {id} along with all of the members of OrganizationUser. The call to /user/ {id} ?projection=BASIC retrieves the same OrganizationUser except it retrieves only a subset of the members of OrganizationUser.

The following is the response payload from a GET method call to /my/user?projection=EMPTY:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:organizationUser xmlns:ns2="http://www.oracle.com/beehive" xmlns:ns3="http://www.oracle.com/beehive/rest">
  <collabId>
    <id>39F7:61B5:user:7B4EEC8DFE384BD5B95CF22E932CD625000000000000</id>
    <resourceType>user</resourceType>
  </collabId>
  <deleted>false</deleted>
  <effectiveExternalInbox>false</effectiveExternalInbox>
  <extendedEnterpriseUser>false</extendedEnterpriseUser>
  <externalInbox>false</externalInbox>
  <timeZoneModified>false</timeZoneModified>
</ns2:organizationUser>

The following is the response payload from a GET method call to /my/user?projection=BASIC. This represents the same user as the previous call, but it contains more information:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:organizationUser xmlns:ns2="http://www.oracle.com/beehive" xmlns:ns3="http://www.oracle.com/beehive/rest">
  <collabId>
    <id>39F7:61B5:user:7B4EEC8DFE384BD5B95CF22E932CD625000000000000</id>
    <resourceType>user</resourceType>
  </collabId>
  <deleted>false</deleted>
  <name>testuser</name>
  <parent xsi:type="ns2:enterprise" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <collabId>
      <id>39F7:61B5:enpr:7ADDEAC1D637D488E040E50A6A923DF900000000021E</id>
      <resourceType>enpr</resourceType>
    </collabId>
    <deleted>false</deleted>
    <allocatedQuota>0</allocatedQuota>
  </parent>
  <snapshotId>00000000000000000000000000247006000001259E8D7B500000000000000000</snapshotId>
  <properties>
    <map/>
  </properties>
  <status>ENABLED</status>
  <effectiveExternalInbox>false</effectiveExternalInbox>
  <extendedEnterpriseUser>false</extendedEnterpriseUser>
  <externalInbox>false</externalInbox>
  <familyName>testuser</familyName>
  <locale>en</locale>
  <personalWorkspace>
    <collabId>
      <id>39F7:61B5:wspr:7B4EEC8DFE384BD5B95CF22E932CD625000000000001</id>
      <resourceType>wspr</resourceType>
    </collabId>
    <deleted>false</deleted>
    <shortWorkspaceId>0</shortWorkspaceId>
  </personalWorkspace>
  <timeZoneModified>false</timeZoneModified>
</ns2:organizationUser>

Consequently, before using a projection, verify with the API reference which members are retrieved. Additionally, if you are unmarshalling objects returned from Oracle Beehive RESTful Web services with a strongly typed language such as Java or C#, ensure that you only dereference values from members returned by the projection that you used. Because a projection returns only a subset of the members of a particular object, languages such as Java and C# will assign default values to members not returned by the projection, and these values are independent of what is returned by the server and thus invalid.

The following samples call the /my/user with an EMPTY projection, then a BASIC projection:

Table 1-4 BDK Projection Examples

Platform Requirements Source Code Files

C#

Refer to "C# BDK Clients"

Refer to "C# BDK Examples"

Flex

Refer to "Adobe Flex Clients"

Refer to "Adobe Flex Samples"

Java

Follow the steps described in "Setup with Third Party APIs"

Refer to "Java BDK Examples"

JavaScript

Refer to "JavaScript BDK Clients"

Refer to "JavaScript Samples"

Creating Objects with Content

The examples in this section describe how to create a Document that contains text. This involves uploading a text document, creating a Document artifact, then associating the text document with the Document artifact.

Step 1   Upload the content

In the POST method /session/upload, specify a unique identifier for the content_id parameter. This is a mandatory parameter even though it is not used if the uploaded content is for a Document or WikiPage artifact. (This arbitrary string value is used to associate the content with a part of an EmailMessage.)

Specify the scope of the upload in the uploadscope parameter. The value of uploadscope is an arbitrary string that binds together multiple content that are uploaded for the same intent, such as multiple parts of an e-mail message. In the payload of the POST request, specify the content you want to upload as raw (binary) data or use the format defined in RFC 1867: Form-based File Upload in HTML:

POST /comb/v1/d/session/upload?content_id=
                                       {unique_identifier}&uploadscope=
                                       {unique_scope}&anticsrf=
                                                                                 {anti-CSRF_token}                                       
                                    

The following is a sample HTTP POST request. It uploads a simple text file with the content Simple Text Doc. The value of the content_id parameter is 1251436206968, which is a unique and arbitrary string. The scope of the upload is scope1251436206968, which is a unique and arbitrary string.

Example 1-1 HTTP POST Request: Upload

POST /comb/v1/d/upload?content_id=
                                         1251436206968&uploadscope=
                                         scope1251436206968&anticsrf=kp3PZtMeXK0%3D HTTP/1.1
Content-Type: text
Accept: application/xml
Authorization: Basic dGVzdHVzZXI6V2VsY29tZTE=
User-Agent: Jakarta Commons-HttpClient/3.1
Host: example.com:7777
Cookie: $Version=0;
JSESSIONID=764ea0511296dfe62f51af159125fd0b9471b8a979195aebe20e8b3cdd9d1d96.e38LbN4RaxeObi0RaNaPbN0Nb3z0;
$Path=/comb
Co7ntent-Length: 15
 
Simple Text Doc
                                      
Step 2   Create the artifact

In the POST method /adoc, specify in the uploadscope parameter the same value you used in the previous step:

POST /comb/v1/d/adoc?content_id=
                                       unique_identifier&uploadscope=
                                       unique_scope&anticsrf=
                                                                                 {anti-CSRF_token}                                       
                                    

The Document resource create method creates a new Document artifact and associates the content you uploaded with the Document's content attribute.

You may attach arbitrary name-value pairs of data to this Document (as well as to any artifact), which can enable end users of your client to manipulate and process documents in your system.


Notes:

 

If you are using form-based upload, then all non-file parameters are ignored and the first file parameter in the submitted payload is used. If more than one file is uploaded, then only the first file is used and the remaining are discarded.

The following is a sample HTTP POST request that creates a Document artifact and associates that artifact with the text file uploaded in Example 1-1, "HTTP POST Request: Upload". Note that the values of uploadscope and content_id and the HTTP session are the same as the previous HTTP POST request. The entity with the resource type afrh specified in parent represents a heterogeneous folder in which the new Document artifact will reside.

Example 1-2 HTTP POST Request: Create Document Artifact

POST /comb/v1/d/adoc?content_id=
                                     1251436206968&uploadscope=
                                     scope1251436206968&anticsrf=kp3PZtMeXK0%3D HTTP/1.1
Content-Type: application/xml
Accept: application/xml
Authorization: Basic dGVzdHVzZXI6V2VsY29tZTE=
User-Agent: Jakarta Commons-HttpClient/3.1
Host: example.com:7777
Cookie: $Version=0;
JSESSIONID=764ea0511296dfe62f51af159125fd0b9471b8a979195aebe20e8b3cdd9d1d96.e38LbN4RaxeObi0RaNaPbN0Nb3z0;
$Path=/comb
Content-Length: 852
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:documentCreator
  xmlns:ns3="http://www.oracle.com/beehive/rest" 
  xmlns:ns2="http://www.oracle.com/beehive">
  <conflictResolutionMode>OVERWRITE</conflictResolutionMode> 
  <ignorePendingConflicts>true</ignorePendingConflicts>
  <name>SimpleDocTest.txt</name>
  <parent>
    <id>005D:7DB4:afrh:6FDCAE7DCA31F7EDE040578C5C8471FB0000000186CF</id>
    <resourceType>afrh</resourceType>
  </parent>
</ns2:documentCreator>
                                  

The following examples demonstrate how to create a Document artifact that contains a text document.

Table 1-5 BDK Creating Objects with Content Examples

Platform Requirements Source Code Files

C#

Refer to "C# BDK Clients"

Refer to "C# BDK Examples"

Java

Follow the steps described in "Setup with Third Party APIs"

Refer to "Java BDK Examples"

JavaScript

Refer to "JavaScript BDK Clients"

Refer to "JavaScript Samples"

Creating Artifacts with Uploaded Content

The examples in this section describe how to create an artifact with uploaded content with the resource's updater. In particular, the examples create a DiscussThis forum by using an uploaded text document.

Step 1   Upload the content

This step is the same as Step 1, "Upload the content" in "Creating Objects with Content".

Step 2   Create the artifact

This step is the same as Step 2, "Create the artifact" in "Creating Objects with Content".

Step 3   Create an artifact with the uploaded document

Some methods require an existing artifact. For example, the POST method /adoc/discuss/ {id} , creates a Topic artifact that has a reference to an artifact identified by {id} . The following example creates a Topic that has a reference to a Document with the enterprise identifier that starts with 39F7. The Topic has a subject testUpdater and contains a short text message defined by <firstPostUpdater> (The text itself is Base64-encoded binary data.)

POST /comb/v1/d/adoc/discuss/
                                       39F7:61B5:adoc:7ADDEAC1D637D488E040E50A6A923DF900000001890C?subject=
                                       testSubject&antiCSRF=
                                       {anti-CSRF_token}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:topicUpdater xmlns:ns2="http://www.oracle.com/beehive" xmlns:ns3="http://www.oracle.com/beehive/rest">
  <firstPostUpdater>
    <bodyUpdater xsi:type="ns2:simpleContentUpdater" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <contentBytes>TGV0cyB0YWxrIGFib3V0IHRoaXMhIA==</contentBytes>
    </bodyUpdater>
  </firstPostUpdater>
</ns2:topicUpdater>
                                    

The following examples demonstrate how to create a Topic with a Document created from an uploaded text file:

Table 1-6 BDK Creating Artifacts with Uploaded Content

Platform Requirements Source Code Files

C#

Refer to "C# BDK Clients"

Refer to "C# BDK Examples"

Java

Follow the steps described in "Setup with Third Party APIs". The logged in user has a TeamWorkspace, the workspace has a default Documents folder, and the user is a Full Member of the workspace.

Refer to "Java BDK Examples"

JavaScript

Refer to "JavaScript BDK Clients"

Refer to "JavaScript Samples"

Examples

Refer to the following pages for more detailed information about creating a BDK client with a particular programming language: