C Using the WebCenter Portal REST APIs

This chapter contains the following topics:

C.1 Introduction to REST

REST (REpresentational State Transfer) is an architectural style for making distributed resources available through a uniform interface that includes uniform resource identifiers (URIs), well-defined operations, hypermedia links, and a constrained set of media types. Typically, these operations include reading, writing, editing, and removing, and media types include JSON and XML/ATOM.

REST commands use standard HTTP methods as requests to point to the resource being used. Every request returns a response, indicating the status of the operation. If the request results in an object being retrieved, created, or updated, the response includes a standard representation of that object.

REST supports multiple clients, both from client machines and other servers, and it can be used from just about any client or development technology, including Java, JavaScript, Ruby on Rails, PHP, .Net, and so on.

Tip:

For a good general introduction to REST, see the Wikipedia article Representational State Transfer at http://en.wikipedia.org/wiki/Representational_State_Transfer.

REST is typically used with Rich Internet Applications (RIA) that are client-side scripted and require the ability to interact with data from a server-side application. For example, the WebCenter iPhone App uses WebCenter Portal REST APIs to interact with a WebCenter Portal application. The native iPhone client is written in Objective-C, and the REST APIs enable the client to send and retrieve application data.

C.2 Understanding the Username-Based Security Token Encryption

To provide additional security, every URI, for both href and template attributes, includes a security token parameter that is based on the authenticated username (a utoken).

The security generation algorithm uses a randomly generated "salt" along with the username. The salt ensures that if any of the parameters used to perform encryption become compromised, existing tokens can be invalidated and new ones generated. Most importantly, because the username is used as part of the user token generation algorithm, the salt prevents having to change all user names in the event of a compromise.

The salt is stored in the Credential Store Framework (CSF) in the map o.webcenter.jf.csf.map against key user.token.salt. You can change the value of this key (and other keys used for token encryption) by accessing CSF in Oracle Enterprise Manager.

Caution:

If you change the encryption key values, all existing username based security tokens will immediately become invalid. Only change these values under extraordinary circumstances, like an algorithm parameter compromise.

C.3 Benefits of Using REST

Many excellent articles have been published about REST and the benefits of the RESTful style of software architecture. Some of these benefits include:

Using "Hypermedia As The Engine Of Application State" (HATEOAS) links to access the REST API helps promote API robustness. Since the clients only use URIs returned from the server, if the server changes the URI format, the client will continue to function properly. See also Understanding the Link Model.
Using the standard HTTP protocol allows network infrastructure to cache REST requests where appropriate, reducing load on both the client and server. See also Managing Caches.
Stateless REST requests allow each request to be served by any number of different servers, helping with scalability.
Using the standard HTTP protocol allows a wide variety of clients to interact with the REST APIs without requiring specialized libraries.

C.4 Introduction to the WebCenter Portal REST APIs

In addition to enabling mobile access, WebCenter Portal REST APIs allow you to take advantage of Web 2.0 technologies like Ajax, JavaScript, and JSON to create rich, interactive browser-based user interfaces and to access and modify WebCenter Portal data. In general, the WebCenter REST commands provide a more natural and easy-to-use alternative to a SOAP-style Web services approach. For more information, see REST API for Oracle WebCenter Portal.

Table C-1 describes the Oracle WebCenter Portal REST APIs provided for WebCenter Portal: Services features.

Table C-1 Summary of WebCenter Tools and Services Features Supported by REST APIs

REST API	Description	Section
Discussions	Enable a client to post, read, update, and delete discussion forums, topics, and messages.	Using the Discussions REST API
Lists	Enables a client to browse all the lists associated with a named portal; search list columns given a search term; create new lists; add, update, and remove list rows; and similar sorts of list-related tasks	Using the Lists REST API
People Connections	Enable a client to view profile data; manage connection lists, feedback, and messages; create new activities and view activities for users, lists, and portals.	Using the People Connections REST APIs
WebCenter Portal	Enable a client to retrieve portal metadata and view, create, update, and delete portal lists and list items. You can also retrieve portal membership information.	Introduction to the WebCenter Portal REST APIs
Content Management	Uses the CMIS (Content Management Interoperability Services) RESTful server binding to provide access to the CM VCR (Content Management Virtual Content Repository).	Content Management REST API
Activity Graph	Enables you to retrieve recommendations for connections, portals, and items using the underlying Activity Graph engine.	Using the Activity Graph REST APIs
Events	Lets you access calendar events associated with a named portal.	Using the Events REST API
Feedback	Enables a client to create, read, and delete feedback in a social networking application.	See Using the Lists REST API
Search	Lets you post, read, update, and delete searches. You can specify keywords and the scope of the search; for example, the iPhone could search for "smith" in all portals, documents and wiki pages.	Using the Search REST APIs
Tags	Enables a client to read, post, update, and delete tags and tagged items.	Using the Tags REST APIs
Navigation	Use the navigation REST APIs to create your own interface for displaying navigations. Note: The navigation REST APIs do not share the resource index described in this chapter.	Using the Tags REST APIs

Note:

XSD files for the following URNs:

urn:oracle:webcenter:activities:stream -> activitystream.xsd
urn:oracle:webcenter:messageBoard -> wall.xsd
urn:oracle:webcenter:people -> people.xsd
urn:oracle:webcenter:people:invitations -> people.xsd
urn:oracle:webcenter:people:person -> people.xsd
urn:oracle:webcenter:search:results -> search.xsd
urn:oracle:webcenter:spaces -> spaces.xsd

can be found in your <WCP_ORACLE_HOME>/webcenter/schemas/ directory.

C.5 Understanding the Link Model

Hypermedia is at the core of two of the most successful Web-based formats: HTML and ATOM. HTML and ATOM allow consumers to navigate to other hypermedia documents through links–for example, clicking on a link to go to a news article.

Hypermedia drives the RESTful application state (known as HATEOAS: Hypermedia As The Engine Of Application State).

Note:

HATEOAS analogy to define application state:

Suppose you are completing your taxes in your favorite browser. You finish entering your W-2 data and move on to deductions when the browser crashes. The state you lost—the fact that you were on deductions and still needed to enter data—is the application state; not the W-2 data entered (that is, change states from the current state).

HATEOAS dictates that this state—the application state—be captured wholly in hypermedia. Application state is where you are in the application, not what data you've entered into the application. One of the benefits of this approach is that it simplifies the client and server, because they do not need to be aware of the state they are in. The link contains all the state information necessary to process the request, so, when the browser restarts and returns to the link, the user will be at the same place in the tax process.

Given a set of top-level URI entry points to a RESTful service, all interactions beyond those entry points are driven by hypermedia links returned in response representations. This link-centered approach helps keep the client from becoming too tightly coupled to the server URLs. The client is using URLs given to it by the server, therefore the client code does not break if the server URLs change format.

Understanding this link model helps you understand how to use the data the service returns to navigate the REST APIs.

This section describes the hypermedia link model used by WebCenter's RESTful services. It includes the following topics:

C.5.1 Using the Resource Index

In WebCenter, the Resource Index is your starting point for all authenticated access. The Resource Index provides access to the set of top-level URI entry points. It provides the way in to all the available WebCenter RESTful services. The Resource Index URI is the only URI that you need to know.

Tip:

A REST client is helpful for generating custom REST requests. For example, a Firefox RESTClient add-on is available at:

http://restclient.net/

Other similar REST clients can also be easily obtained.

The WebCenter Resource Index URI is:

http://host:port/rest/api/resourceIndex

Note:

Access to the Resource Index always requires authentication; however, you can (optionally) access the CMIS resource entry point anonymously using the following URI:

http://host:port/rest/api/cmis/repository

The first step in using the WebCenter Portal REST APIs is to send a GET request to the Resource Index. The response varies depending on the services available and the media type of the request. The example below shows how the response might look if you made an Ajax request using JavaScript (and possibly a client-side scripting library, such as Dojo) to retrieve the JSON data for the Resource Index. Note that this is an abridged sample response and does not include all of the links actually present in a real response.

Example: Response to a GET on the Resource Index

{
  "resourceType": "urn:oracle:webcenter:resourceindex",
  "links": [
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:messageBoard",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "resourceType": "urn:oracle:webCenter:cmis",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:discussions:forums",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "resourceType": "urn:oracle:webcenter:resourceindex",
      "rel": "self",
      "href": "http://host:port/rest/api/resourceIndex",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:activities:stream",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:people:person",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:feedback",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:spaces",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    },
    {
      "template": "opaque-template-uri",
      "resourceType": "urn:oracle:webcenter:people",
      "href": "opaque-uri",
      "capabilities": "urn:oracle:webcenter:read"
    }
  ]
}

By interpreting the links returned in the Resource Index data, you can retrieve the URI entry point for an individual service by locating the URI for the resource type you want to use. You can then continue navigating through the hypermedia until you can perform the required operation. The following example shows a method that locates a URI given the Resource Index JSON data.

Example: Locating the URI for a Particular Service in the Resource Index

/* Parse the resourceIndex to find the specified URL and
 * return it.
 *
 * @Param jsonData the JSON data retrieved from calling
 *        the /rest/api/resourceIndex URL.
 * @Param strResourceType the resource type of the URL
 *        you want to retrieve from the resourceIndex data.
 *        E.g., 'urn:oracle:webcenter:activities:stream'
 */
function getResourceURL(jsonData, strResourceType)
{
  // Using the HATEOAS model, we browse the returned links
  // looking for the one with the correct resource type.
  for (var i = 0; i < data.links.length; i++) {
    if (data.links[i].resourceType == strResourceType) {
      return data.links[i].href;
    }
  }
}

C.5.2 Anatomy of a Link

The resourceType, rel, and capabilities attributes of the hypermedia link provide metadata that enable clients to determine which URI (href or template) to use, without having to parse the URIs directly. The URIs are opaque—the metadata determines which link is useful in a given circumstance.

The following examples show the anatomy of a hypermedia link as XML and in JSON document fragments, respectively.

Example: Link in an XML Document Fragment

<links>
  <link href="opaque-URI"
        template="opaque-template-URI (optional)"
        rel="rel-name"
        title="human-readable-title (optional)"
        type="media-type (optional)"
        resourceType="resource-type"
        capabilities="operation"/>
  ...repeat as needed...
</links>

Example: Link in a JSON Document Fragment

"links": [
  {
    "href":"opaque-URI",
    "template":"opaque-template-URI (optional)",
    "rel":"rel-name",
    "title":"human-readable-title (optional)",
    "type":"media-type (optional)",
    "resourceType":"resource-type",
    "capabilities":"operation"
  },
  ...repeat as needed...
]

Multiword field, element, and attribute names are formatted in camel case, unless the representation is attempting to conform to a specification not under the service author's direct control. Acronyms are treated as normal words with their case adjusted accordingly (for example, fooXml or xmlFoo) as shown in the following examples:

Example: XML Naming Convention

<myElement>text</myElement>

Example: JSON Naming Convention

{"myElement": "text"}

This section includes the following topics that describe the different attributes of the hypermedia link:

C.5.2.1 Resource Type

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

For more information, see Navigating Hypermedia Using HTTP.

C.5.2.2 Relationship

The rel link attribute indicates the relationship of the linked object to the current object (that is, the object that contains the list of links). The value of this attribute is a space-separated list of the following currently supported values:

self - The linked object is the current object
related - The linked object is related to the current object
via - The linked object is the source of the information for the current object
alternate - The linked object is a substitute for the current object (typically, the same object in another format, such as an HTML page that displays the current object)
urn:oracle:webcenter:parent - The linked object is the parent of the current object. That is, the linked object owns the current object

Note:

Some REST APIs for some WebCenter features may contain additional rel link attributes. See the REST API documentation for each specific feature for more information.

C.5.2.3 Capabilities

The capabilities link attribute indicates which methods are supported by the linked resource.

Links are returned only if a client is allowed to access that resource. User authorization can affect the capabilities a client has with the links returned in a response representation. In general, services only return the capabilities that the current authorized user has permission to execute and that the resource supports.

If there is no link, then the client cannot access the resource. If a link has no capabilities, then it is not returned to the client, meaning that the client does not have permission to do anything with that link (even read it).

Capability-based expression of hypermedia links communicates the range of operations that the client can expect to succeed, which allows the client to dynamically configure any associated UI to provide the best overall user experience.

The value of this attribute is a space-separated list of the following values:

urn:oracle:webcenter:create - This maps to the HTTP verb POST
urn:oracle:webcenter:read - This maps to the HTTP verb GET
urn:oracle:webcenter:update - This maps to the HTTP verb PUT
urn:oracle:webcenter:delete - This maps to the HTTP verb DELETE

Note:

The top-level resourceIndex links only returns the read capability, even if the user is authorized with additional capabilities.

Note:

Querying a resource for the allowed HTTP verbs using OPTIONS returns the verbs that the resource can support in general, and does not take a user's access into account. The capabilities attribute in a link describes exactly what the current user can do with the current resource. OPTIONS may return more HTTP verbs than the current user is allowed.

C.5.2.4 Media Type

The type link attribute indicates the media types supported by the linked object.

All REST services, except for CMIS, support both XML (application/xml) and JSON (application/json) media type. CMIS currently supports only ATOM. For more information about the CMIS REST API, see Content Management REST API.

C.5.2.5 Templates

The template link attribute indicates that the client can use a URI template, instead of the href URI, to provide parameterized values for the linked object. Links must include at least an href or a template URI, but can include both.

Some hypermedia links support request query parameters that allow the client to configure the link in different ways. Rather than force the client to know the URI format and manually build the URI, URI templates are used. These templates allow client code to easily insert data into a URI without having to understand exactly how the URI works. This maintains the opacity of hypermedia URIs and protects the client from changes to the URI format.

The example below shows a URI template including several request query parameters.

Example: URI Template

http://host:port/.../lists?startIndex={startIndex}&itemsPerPage={itemsPerPage}&q={searchTerms}&projection={projection]

WebCenter Portal REST APIs use a simple slot replacement syntax that follows many industry URI template schemes.

For example, using the template above, to see 10 list items (default) on the first page, the client would provide a value of 1 for the startIndex parameter and a value of 10 for the itemsPerPage parameter, as shown below.

Example: URI Template with Parameter Values

http://host:port.../lists?startIndex=1&itemsPerPage=10

Note:

All unused parameters must be removed from a template before it can be used. Clients may not submit unprocessed templates to the service that produced it; doing so results in undefined behavior, generally returning a status code of 500.

Clients must process templates into valid URI form before submitting to the server. Clients must replace slots with appropriate values, taking care to properly URI encode any value replacing the slot token. If a client does not have a suitable value for one or more of the slots in the template, then it must replace the slot token with an empty string.

You must URL-encode special or reserved character in parameter values. For example, to search lists for a person named Günter, you must URL-encode the ü as shown below.

Example: Encoding Special Characters in URI Templates

http://host:port.../lists?q=G%FCnter

C.5.2.5.1 Common Request Query Parameters

Many resources support a common set of request query parameters. For example, when retrieving a collection of entities, it is common to change the shape of the results set by limiting the quantity or details of the results. The REST framework uses the following request parameters to scope results and provide security:

startIndex - Specifies the index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.
itemsPerPage - Specifies the maximum number of results to return in the response (1-n). This is used for pagination.
q - Specifies implementation-specific searching. Searches may be specified using the following format (square brackets [] denote optional values):
```
[[field1:[operand]][:]value1[;field2:operand:value2]]
```
For example:
```
&q=login:equals:monty
&q=title:contains:issues
&q=creator:equals:monty;description:contains:Urgent
```
While each resource uses the same format for the q parameter, the way search is implemented is different depending on the resource being searched. For more information about how each resource implements search, see the topic for the specific service.
projection - Reserved for implementation-specific projection of model representations, such as variable recursion depth, field or attribute filtering. Valid values are summary or details.

For example, requesting a projection of summary for a collection of lists, returns only the title, description, and hypermedia links. Requesting a projection of details results in the server sending back a collection of lists that includes all the column metadata for each list. This may require additional processing time or database queries on the server.

The following example request results in the response entity containing a deeper object graph.
```
http://host:port/...lists&projection=details
```
data - This parameter accepts a comma separated list of data sets and items. This parameter lets clients specify what data they would like to receive. For example, a mobile device application might use this parameter to limit the amount of XML data returned. If both the projection and data query string parameters are present, the data parameter will be used to determine which data to return. If you specify the constant 'data' as the data parameter, all the standard information will be returned for the resource.

For information about how these parameters are supported by specific resources, see the topic for the appropriate service.

C.6 Understanding Items Hypermedia

A collection of items makes up the actual content of responses. This is at the same level as the links section described previously. Each item (including the top-level tag in each response) has one common attribute (resourceType) in addition to resource-specific content and format. For details beyond the resourceType, see the topic for the specific service.

C.7 Navigating Hypermedia Using HTTP

You can navigate REST service hypermedia in a similar way to that used to browse and interact with HTML or an ATOM feed. Interactions are performed on the resources identified by links using HTTP methods. The REST services return response codes and response bodies to the client, and the client uses the hypermedia in the response to drive further interactions.

Table C-2 describes the general pattern followed when constructing opaque resource URIs. The resourceType differentiates whether the HTTP method operates on a collection of resources or an individual resource.

Table C-2 HTTP Methods

HTTP Method	Response for a Collection of Resources	Response for an Individual Resource
`GET`	Returns resource collection container (200 HTTP response code)	Returns resource (200 HTTP response code)
`PUT`	Cannot update a collection of resources (405 HTTP response code)	Updates and returns resource (200 HTTP response code)
`POST`	Creates and returns a new resource within the collection. Note: Can return a 201 or 204 HTTP response code. The returned code depends on whether the newly created object is directly addressable or not. For instance, activities cannot be addressed individually, so they return a 204 no-content response code.	Cannot create a resource within an individual resource (405 HTTP response code)
`DELETE`	Cannot delete a collection of resources (405 HTTP response code)	Deletes resource (204 HTTP response code)

Collection resources generally support reading a collection (GET) and creating a subordinate to that collection (POST). Individual resources generally support reading a resource (GET), updating a resource (PUT), and deleting a resource (DELETE).

C.7.1 HTTP Response Status Codes

Table C-3 describes the potential response status codes.

Table C-3 HTTP Response Status Codes

HTTP Response Status Code	Description
200	OK. Upon successful completion of a `GET` or `PUT`. This is accompanied by a resource representation as a response body.
201	Created. Upon successful completion of a `POST`. This has a location header to the newly-created resource.
204	No content, or any request that does not return content. For example, creating an object that cannot be linked. Upon successful completion of a `DELETE`.
400	Bad Request. The URI was malformed or could not be processed; for example, the IDs were not formatted correctly, or the ID was supplied in the URI on a `POST`.
401	Unauthorized. Client may retry by submitting credentials. This may be accompanied with a fault response body to help diagnose the issue.
403	Forbidden. Client does not have permission to perform a particular action, such as creating or deleting a resource. Re-authenticating as the same user does not help. This may be accompanied with a fault response body to help diagnose the issue.
404	Not Found. Referencing a specific resource with an ID, but that resource does not exist.
405	Method Not Allowed. This includes a list of valid methods for the requested resource.
406	Not Acceptable. The Accept header media type(s) sent by the client are not supported for the requested operation.This may be accompanied with a fault response body to help diagnose the issue.
409	Conflict. Possibly the resource ID is in use, or an entity has been modified by another process during an update.This may be accompanied with a fault response body to help diagnose the issue.
422	Bad entity body, the data in the body, although syntactically correct, was not valid, or could not be processed; for example, invalid data when updating a row.
500	Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.
501	Not Implemented. The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.

C.8 Security Considerations for WebCenter Portal REST APIs

All of the WebCenter REST URIs reference protected resources (similar to protected web pages) and require authentication for access.

Note:

The one exception to the authenticated access rule is access to the CMIS resources. CMIS resources can be accessed anonymously through the CMIS URI entry point:

http://host/port/rest/api/cmis/repository

You can pass this authentication in with the request using basic authentication, or you can configure the client and the WebCenter REST service to use single sign-on. For more information about single sign-on, see Configuring SSL in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

Basic authentication sends the user's password in plain text. If you use this type of authentication, you should consider securing the connection using SSL. For more information, see Configuring SSL in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

To provide additional security, every URI, for both href and template attributes, includes a security token parameter. The security token is user-scoped. This means that it is based on and scoped to an authenticated user and can be bookmarked or cached across that user's sessions. These security tokens help prevent Cross-Site Request Forgery (CSRF) attacks.

For example:

<link
  template="opaque-template-uri/@me?startIndex={startIndex}&itemsPerPage={itemsPerPage}
     &token=generated-token" resourceType="urn:oracle:webcenter:messageBoard"
     href="opaque-uri/@me?token=generated-token" capabilities="urn:oracle:webcenter:read"
/>

Note:

The security token is not used for authentication or identity propagation.

WebCenter Portal REST APIs operate under the identity of the authenticated user. For example, the portal REST APIs only return information for, and allow changes to, portals to which the user has access.

C.9 Security Considerations for CMIS REST APIs

The CMIS REST APIs do not use the same authentication scheme as the other WebCenter Portal REST APIs. Whereas other WebCenter Portal REST APIs do not allow unauthenticated access and prompt the user for authentication before allowing access, the CMIS REST APIs do allow unauthenticated access.

If a document requires authentication information and does not receive that information (because it is being accessed by an unauthenticated user), a 404 error is returned. This does not necessarily mean that the document cannot be found, rather that the (unauthenticated) user does not have the appropriate permissions to access the document. For the request to succeed, it should include basic authentication headers to identify the current user.

CMIS stands for Content Management Interoperability Services, a standard REST interface for Enterprise Content Management Systems. For more information, see Content Management REST API.

C.10 Understanding Common Types

This section describes the common types that are shared by multiple WebCenter Portal REST APIs.

C.10.1 Common Types

Common types provide a consistent way to reference objects used in the WebCenter Portal REST APIs.

This section includes the following topics:

C.10.1.1 personReference

This is a generic data type that represents a user in the system. It is used by several APIs, for example to identify the author of a message board or feedback message, or a user's manager or direct reports. It is made up of the following elements:

guid - The GUID of the user
id - The login ID of the user
displayName - The display name of the user

The personReference also includes a link to the user's profile icon. You can control the size of the icon by providing values: small, medium, or large.

Depending on where the personReference type is included, it can also return links to the associated REST APIs of the generating response. For example, if the personReference type is included as the author in a message board response, it includes links to message board services.

C.10.1.2 groupSpaceReference

This is a generic data type that represents a portal. It is used by several APIs, for example in the activity stream, to identify a portal in which a particular activity occurred. It is made up on the following elements:

guid - The GUID of the portal
name - The name of the portal
displayName - The display name of the portal

The groupSpaceReference also includes an html link, rest link, and icon link.

C.10.2 Portable Contact Types

Portable Contact types provide users with a standard way to access their address books and friends lists over the Web. Portable Contact types are used by the Profile component of the People Connections service.

Note:

These types are based on the Portal Contact Types in WebCenter. They may include additional data.

This section includes the following topics:

C.10.2.1 name Portable Contact Type

This is a portable contact type that provides information about the user's name. It is made up of the following elements:

formatted - The formatted version of the full name of the user, for example, Michael David Jones Ph.D.
familyName - The family name, or last name, of the user, for example Jones
givenName - The given name, or first name, of the user, for example Michael
honorificSuffix - The honorific suffix of the user, for example, Esq. or Ph.D.
initials - The first initials of the user, for example, M. D.
maidenName - The maiden name of the user

Some of the elements may not be present depending on the user repository configuration and data.

C.10.2.2 address Portable Contact Type

This is a portable contact type that provides information about the user's address. It is made up of the following elements:

formatted - The formatted version of the full address
type - The type of the address, for example, Home, Work
streetAddress - The street address
poBox - The post office box number
locality - The city or locality
region - The state or region
postalCode - The zip code or postal code
country - The country

Some of the elements may not be present depending on the user repository configuration and data.

C.10.2.3 organization Portable Contact Type

This is a portable contact type that provides information about the user's organizational affiliation. It is made up of:

name - The name of the organization
employeeNumber - The employee number of the user
employeeType - The employee type of the user.
department - The department within the organization to which the user belongs
defaultGroup - The default group to which the user belongs
title - The job title of the user within the organization
description - A textual description of the user's role within the organization
expertise - The expertise of the user within the organization
startDate - The date when the user joined the organization

Some of the elements may not be present depending on the user repository configuration and data.

C.10.2.4 value Portable Contact Type

This is a generic object that contains data for a wide variety of contact information. It is made up of the following elements:

primary - A boolean value that identifies whether this is the primary piece of information of this type for this person. The primary element may not be present and is only relevant if there are multiple values for the same type of data.
value - The value for this type
type - The type of information. Valid types are:
- standard: with valid values of work, home, other
- phoneNumber: with valid values of work, home, fax, pager, mobile
- photos: with a valid value of thumbnail

C.11 Managing Caches

Client-side developers need to know how to handle HTTP cache headers in both requests and responses. Individual resources that have a "last modified" date are also return entity tags. The entity tags can be used to make retrieval of a specific entity more efficient. To learn more about the use of entity tags in caching, refer to the Hypertext Transfer Protocol specification:

http://www.w3.org/Protocols/

C.12 Configuring a Proxy Server

This section explains how to set up a simple, response-rewriting reverse HTTP proxy on an Apache server. A proxy server is typically employed to avoid cross-domain request problems associated with making XMLHttpRequest (XHR) calls from a browser client. These calls are typically associated with the Ajax development technique for creating rich, interactive client-side interfaces. REST APIs are typically used within this kind of client-side development scenario.

Note:

This section illustrates a simple example of setting up a proxy server on Apache. For more detailed information, refer to the Apache Server documentation available at http://httpd.apache.org/docs. You can also use Oracle HTTP Server (OHS) for your proxy server.

The basic steps for setting up a proxy server on Apache are:

Obtain access to an Apache server. Oracle recommends Apache 2.2.7 or a later version.
Make sure the server has the mod_substitute and mod_proxy modules installed. Note that Apache versions 2.2.7 and later include mod_substitute by default. It is also possible to use mod_sed or mod_line_edit, however these configurations are not supported by Oracle.

Open the httpd.conf or the virtual host configuration file, and add the following lines, substituting your server name/information where appropriate:

ProxyRequests           Off
LoadModule              substitute_module       modules/mod_substitute.so
SetOutputFilter         SUBSTITUTE
 
ProxyPass               /rest/api/              http://myhost:8888/rest/api/
ProxyPassReverse        /rest/api/              http://myhost:8888/rest/api/
Substitute              s|myhost|yourhost|n
 
ProxyPass               /pathname/rest/api/        http://myhost:8888/rest/api/
ProxyPassReverse        /pathname/rest/api/        http://myhost:8888/rest/api/
Substitute              s|myhost:8888/rest/api|yourhost/pathname/rest/api|n

Note:

Two servers are being proxied in this example scenario. Note that the following two calls are actually talking to these two different servers, but they appear to clients to be the same server host:

http://myhost/rest/api/resourceIndex

http://myhost/pathname/rest/api/resourceIndex

Restart the Apache server. For example, on Linux, you could do this:
```
sudo /etc/init.d/httpd restart
```

Note that on some configurations of Linux, proxying with Apache in this fashion requires you tell selinux to allow outbound connections from httpd. You can accomplish this by enabling the httpd_can_network_connect flag in selinux's GUI or through the command line.

Developer Tip:

Set the UserDir permissions in httpd.conf to allow users to drop these files in their own public_html directory. For example, you might hit http://host/~yourname/sample.html to access your sample application, and then have the sample application make XHR calls to http://host/rest/api/resourceIndex.

C.13 WebCenter Portal REST API Examples

This section includes some examples illustrating how to use the WebCenter Portal REST APIs. It includes the following topics:

C.13.1 Navigating the Message Board Hypermedia

This section includes examples to illustrate how to navigate the REST service hypermedia. The examples show how to read messages on a message board, post messages to another user's message board, delete unwanted messages, and filter message board messages.

This section includes the following topics:

C.13.1.1 Accessing the Resource Index

The first step is always to access the Resource Index as shown in the example below.

Example: Accessing the Resource Index

GET /resourceIndex

This request returns a list of the top-level URI entry points to the RESTful services, including the entry point for the message board:

Example: Response to Accessing the Resource Index

200 OK
Accept: application/json;charset=UTF-8

{
  "resourceType": "urn:oracle:webcenter:resourceindex",
  "links": [
    {
      "resourceType": "urn:oracle:webcenter:resourceindex",
      "capabilities": "urn:oracle:webcenter:read",
      "rel": "self",
      "href": "http://host:port/rest/api/resourceIndex"
    },
    {
      "resourceType": "urn:oracle:webcenter:messageBoard",
      "capabilities": "urn:oracle:webcenter:read",
      "href": "opaque-messageBoard-URI"
    },
  ...repeating for other services...
}

You can examine this list to find the URI that you require to access your message board. You should look for the link with a resourceType of urn:oracle:webcenter:messageBoard. The href for this link is the one that you require to access your message board.

For other resources rel, type, and template also help find the correct link.

C.13.1.2 Reading Messages

Once you have determined the correct URI for your message board, you can send a GET request to that URI to read your messages.

To read messages on a message board, you must be logged in.

Example: Retrieving Messages from Your Message Board (GET)

GET /opaque-messageBoard-URI

The response provides information about all the messages on your message board:

Example: Response to Retrieving Messages from Your Message Board

200 OK
Accept: application/json;charset=UTF-8
 
{
  "resourceType": "urn:oracle:webcenter:messageBoard",
  "links": [
    {
      "resourceType": "urn:oracle:webcenter:messageBoard",
      "capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:create",
      "rel": "self",
      "href": "opaque-messageBoard-URI"
    }
  ]
  "items": [
    {
      "resourceType": "urn:oracle:webcenter:messageBoard:message",
      "links": [
        {
          "resourceType": "urn:oracle:webcenter:messageBoard:message",
          "capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:delete",
          "rel": "self",
          "href": "opaque-message-URI"
        }
      ]
      "id": "89add57c-7a35-4d35-b24f-ea9259612eb8",
      "body": "What's up?  It's been a while.  Some of us are going to Conner O'Neal's after work.  Want to go?",
      "created": "2009-09-10T11:18:46.696-0700",
      "author": {
        "id": "carl",
        "displayName": "carl",
        "guid": "649A27F09D5C11DEBFAA799CBD41D9B8",
        "links": [
          {
            "resourceType": "urn:oracle:webcenter:people:person",
            "capabilities": "urn:oracle:webcenter:read",
            "rel": "via",
            "href": "opaque-person-URI"
          },
          {
            "resourceType": "urn:oracle:webcenter:messageBoard",
            "capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:create",
            "href": "opaque-messageBoard-URI-for-Carl"
          },
          {
            "type": "text/html",
            "resourceType": "urn:oracle:webcenter:spaces:profile",
            "capabilities": "urn:oracle:webcenter:read",
            "rel": "alternate",
            "href": "opaque-profile-URI"
          }
        ]
      },
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 1,
}

From the response you can see that you have read and create capabilities on your message board. So you can read its contents and post new messages.

In addition, the response also includes a collection of items (in this case the collection consists of just a single item). These items, with a resourceType of urn:oracle:webcenter:messageBoard:message, are the messages on your message board. The capabilities attribute for the message indicates that, for this particular message, you can read it or delete it from your message board.

For each message, the response provides the following information:

id - the identifier of the message
body - the text of the message
author - the author of the message. The author element is also made up of several other elements:
- id - the identifier, or user name, of the author of the message
- displayName - the name of the author, formatted for display
- guid - the globally unique identifier of the author

Within the author element there is also a collection of three links. The resourceType of these links are:

urn:oracle:webcenter:people:person - enables you to view information about the author of the message
urn:oracle:webcenter:messageBoard - enables you to read or create a message on the author's message board
urn:oracle:webcenter:spaces:profile - enables you to read a text/html document of the author's profile

C.13.1.3 Creating a New Message

Now that you have read the message on your message board, you probably want to reply to Carl on his message board. To do this you should send a POST request to the URI for Carl's message board.

To find the correct URI, use the href from the author link with resourceType of urn:oracle:webcenter:messageBoard.

A POST request creates a subordinate resource of the resource to which you post it. In this case, we are posting to the messageBoard, so we should post its subordinate resource: message:

Example: Creating a Message on Another User's Message Board (POST)

POST opaque-messageBoard-URI-for-Carl
Accept: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
 
{
    "body": "sure; see you guys at 6."
}

The response shows that your message was successfully created on Carl's message board:

Example: Response to Creating a Message on Another User's Message Board

201 Created
Content-Type: application/json;charset=UTF-8
 
{ 
  "id": "36b8464f-afda-44b5-90ad-8ecedcb040a3", 
  "body": "sure; see you guys at 6.", 
  "created": "2009-09-10T12:21:09.785-0700", 
  "resourceType": "urn:oracle:webcenter:messageBoard:message", 
  "links": [ 
    { 
      "resourceType": "urn:oracle:webcenter:messageBoard:message", 
      "capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:update urn:oracle:webcenter:delete", 
      "rel": "self", 
      "href": "opaque-message-URI" 
    },
  "author": { 
    "id": "mike", 
    "displayName": "mike", 
    "guid": "649657609D5C11DEBFAA799CBD41D9B8", 
    "links": [ 
      { 
        "resourceType": "urn:oracle:webcenter:people:person", 
        "capabilities": "urn:oracle:webcenter:read", 
        "rel": "self", 
        "href": "opaque-person-URI" 
      }, 
      { 
        "resourceType": "urn:oracle:webcenter:messageBoard", 
        "capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:create", 
        "href": "opaque-messageBoard-URI" 
      }, 
      { 
        "type": "text/html", 
        "resourceType": "urn:oracle:webcenter:spaces:profile", 
        "capabilities": "urn:oracle:webcenter:read", 
        "rel": "alternate", 
        "href": "opaque:profile:URI" 
      } 
    ] 
  }
  ] 
}

C.13.1.4 Updating a Message

A PUT request is very similar to a POST request, except that it is performed on the resource being edited, instead of on the parent resource.

From the response to your earlier POST request, when you created your message on Carl's message board, you can see that you have read, update, and delete capabilities on the message. You can also see that the href provides the URI for your message. Something came up at work and you must stay a bit later. Using the URI for your message, you can now send a PUT request to update the message and let Carl know that you are going to be late.

Example: Updating a Message (PUT)

PUT opaque:message:URI
Accept: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
 
{
    "body": "working late; see you guys at 7."
}

The response is nearly identical to that of POST, except that the body contains your updated message:

Example: Updating a Message

200 OK
Content-Type: application/json;charset=UTF-8
 
{ 
  "id": "36b8464f-afda-44b5-90ad-8ecedcb040a3", 
  "body": "working late; see you guys at 7.", 

...deleted for brevity...

}

C.13.1.5 Deleting a Message

Performing a DELETE request on a resource deletes it, if you have the delete capability on the resource. The link to your message on Carl's message board supports delete.

You decide to delete the message that you left on Carl's message board:

Example: Deleting a Message (DELETE)

DELETE opaque:message:URI

The response is simply a status code of 204:

Example: Response to Deleting a Message

204 NO CONTENT

Note:

DELETE is idempotent, meaning that it can be sent multiple times with the same result. Therefore if you try to delete the same object twice, you still receive the same 204 response even though it has previously been deleted.

C.13.1.6 Filtering Messages

Messages can be filtered (using the HTTP verbs GET, POST, and PUT) based on visibility criteria. Messages posted on message boards falls into the following visibility categories:

Public
Private
Hidden
Public and hidden
Private and hidden

C.13.1.6.1 Public vs Private Messages

The owner of a message board can mark any message as private. When a message is marked as private, that message is not visible to anyone other than the owner of the message. By default, all messages are public.

Messages can also be sent as private messages. If Mike, for example, is viewing Carl's message board, only public messages (including those sent or received as private) will be visible to user Mike.

C.13.1.6.2 Hidden vs Non-hidden Messages

The owner of a message board can mark any message as hidden. When a message is marked as hidden, that message will not be visible to the message board's owner, but will remain visible to anyone else viewing that person's message board.

The following examples show how to retrieve,

Example: Retrieving Filtered Messages (GET)

   all
     rest/api/messageBoards/person/@me 
   private
     rest/api/messageBoards/person/@me/private
   public
     rest/api/messageBoards/person/@me/public
   hidden and public
     rest/api/messageBoards/person/@me/hidden 
   private and hidden
     rest/api/messageBoards/person/@me/private_hidden

person
```
   rest/api/messageBoards/person/<GUID> 
```
Note that the GUID of the logged in user for whom to retrieve messages is required.
space-guid
```
   rest/api/messageBoards/space/<GUID>
```
Note that visibility-based filtering is not available for space-guid.

Example: Using Filtering for New Messages (POST)

   all
     rest/api/messageBoards/person/@me 
   private
     {"body" : "<BODY_CONTENT>","visibilityType" : "private"}
   public
     {"body" : "<BODY_CONTENT>","visibilityType" : "public"}
   hidden and public
    {"body" : "<BODY_CONTENT>","visibilityType" : "hidden"}
   private and hidden
     {"body" : "<BODY_CONTENT>","visibilityType" : "private_hidden"}

person

   rest/api/messageBoards/person/<GUID>

For a GUID other than that of "me":

   public 
     {"body" : "<BODY_CONTENT>","visibilityType" : "public"}
   private
     {"body" : "<BODY_CONTENT>","visibilityType" : "private"}

space-guid
```
   rest/api/messageBoards/space/<GUID>
```
Note that visibility-based filtering is not available for space-guid.

Example: Using Filtering for Modified Messages (PUT)

   all
     rest/api/messageBoards/person/@me/messages/<msg guid>
   private
     {"body" : "<BODY_CONTENT>","visibilityType" : "private"}
   public
     {"body" : "<BODY_CONTENT>","visibilityType" : "public"}
   hidden and public
    {"body" : "<BODY_CONTENT>","visibilityType" : "hidden"}
   private and hidden
     {"body" : "<BODY_CONTENT>","visibilityType" : "private_hidden"}

person

   rest/api/messageBoards/person/<GUID>/messages/<msg guid>

For a GUID other than that of "me":

   public 
     {"body" : "<BODY_CONTENT>","visibilityType" : "public"}
   private
     {"body" : "<BODY_CONTENT>","visibilityType" : "private"}

space-guid
```
   rest/api/messageBoards/space/<GUID>/messages/<msg guid>
```
Note that visibility-based filtering is not available for space-guid.

C.13.2 Displaying Activity Stream Data

To properly display Activity Stream data, you must:

Retrieve the Activity Stream URI entry point
Retrieve the Activity Stream data
Process the Activity Stream data for display

This sample is available on the Oracle WebCenter Portal Demonstrations and Samples page on the Oracle Technology Network (OTN) at:

http://www.oracle.com/technetwork/middleware/webcenter/ps3-samples-176806.html

In the following example:

The getResourceURL method shows you how to retrieve the URI entry point for the Activity Stream service by retrieving the JSON data for the main Resource Index (/rest/api/resourceIndex) and locating the URI for the Activity Stream resource in that data.
The formatMessage method processes the Activity Stream data into a displayable format. This involves locating an individual message and replacing any template parameters in the message with the name of the object or user that corresponds to that parameter. The parameters also include links to display the object or user. They may contain links to REST services for those objects or users, if available.

Note:

To get the Resource Index and Activity Stream JSON data, make Ajax requests using Javascript (and possibly a client-side scripting library like Dojo) and pass the resulting data into the appropriate methods.

Example: Displaying Activity Stream Data

/* Parse the resourceIndex to find the specified URL and
 * return it.
 *
 * @Param jsonData the JSON data retrieved from calling
 *        the /rest/api/resourceIndex URL.
 * @Param strResourceType the resource type of the URL
 *        you want to retrieve from the resourceIndex data.
 *        E.g., 'urn:oracle:webcenter:activities:stream'
 */
function getResourceURL(jsonData, strResourceType)
{
  // Using the HATEOAS model, we browse the returned links
  // looking for the one with the correct resource type.

  for (var i = 0; i < data.links.length; i++) {
    if (data.links[i].resourceType == strResourceType) {
      return data.links[i].href;
    }
  }
}

/* Parse the resourceIndex to find the activity stream URL and
 * then load it.
 *
 * @Param jsonData the JSON data retrieved from calling
 *        the /rest/api/resourceIndex URL.
 */
function getActivitiesURL(jsonData)
{
  // Parse the JSON data to get the activities URI entry point.

  var strHref = getResourceURL(jsonData,
    'urn:oracle:webcenter:activities:stream');

  // INSERT CODE HERE: Implement getting the JSON data from the
  // strHref URL with the Accept header set to "application/json",
  // and use the formatMessage(index, jsonData) function to get
  // the displayable activity message for each activity.

}

/* Replace activity message parameters.
 *
 * @Param index the index of the activity to process
 * @Param jsonData the JSON data retrieved from calling
 *        the /rest/api/resourceIndex URL.
 */
function formatMessage(index, jsonData)
{
  var activity = jsonData.items[index];
  var strMessage = activity.message;

  // Look for activity parameters and replace them in the message.

  if (activity.templateParams && activity.templateParams.items) {
    for (var i = 0; i < activity.templateParams.items.length; i++) {
      var param = activity.templateParams.items[i];

      // Each parameter also has a set of links which at least
      // includes an HTML link and possibly a REST API link.

      strMessage = strMessage.replace(param.key, param.displayName);
    }
  }
  if (activity.detail) {
    strMessage = strMessage + "<br><font size='1'>" +
      activity.detail + "</font>";
  }
  return strMessage;
}

C.13.3 Updating User Status

The following example shows how to use REST APIs to update a user's WebCenter Portal profile status.

Note:

You must host the sample on a web server (for example, Apache or Oracle HTTP Server) or an application server. To avoid cross site scripting errors, you should proxy URL access to the REST service. On Apache or OHS, the conf commands would look like (change myspaceshost and port accordingly):

ProxyPass /webcenter/ http://myspaceshost:port/webcenter/
ProxyPassReverse /webcenter/ http://myspaceshost:port/webcenter/
ProxyPass /rest/ http://myspaceshost:port/rest/
ProxyPassReverse /rest/ http://myspaceshost:port/rest/
ProxyPreserveHost on

This sample is available on the Oracle WebCenter Portal Demonstrations and Samples page on the Oracle Technology Network (OTN) at:

http://www.oracle.com/technetwork/middleware/webcenter/ps3-samples-176806.html

Updating user status involves making a sequence of asynchronous AJAX calls to get the URL for the status object:

urn:oracle:webcenter:resourceindex
   urn:oracle:webcenter:people
      urn:oracle:webcenter:people:person:status

The HTML page for updating user status includes an input field where users can enter the new status message (statusMessage). Clicking the Update Status button (or pressing Enter) calls the updateStatus method to make the initial call to the Resource Index.

Example: HTML Body

<body>
<div>New status message:&nbsp;<input id="statusMessage" type="text"
   onkeyup="{if (event.keyCode==13) updateStatus();}" maxlength="250"
   size="60" /></div>
<div>
<button id="button1" onclick="updateStatus();">Update Status</button>
</div>
<div id="statusResults"></div>
</body>

The following example shows the HTML page.

Figure C-1 New Status Message HTML Page

The code in the following example retrieves the Resource Index (resourceIndexURL variable set to /rest/api/resourceIndex). The Resource Index is returned as an AJAX request object (resourceIndexRequest).

Example: Retrieving the Resource Index

function updateStatus() {
   // Set the UI to busy state. This is cleared in the success and error callbacks
   setUIBusy("Updating status...");
   //get the Resource Index
   resourceIndexRequest.get(
      resourceIndexURL,
      resourceIndexCallback,
      clearUIBusy);
}

The getResourceURL method shown in the following example traverses the links in the data returned by a REST call to find a specified string (URN) that identifies the required resource type.

Example: Traversing the Links

function getResourceURL(data, strResourceType) {
   for (var i = 0; i < data.links.length; i++) {
      if (data.links[i].resourceType == strResourceType) {
         return data.links[i].href;
      }
   }
   return null;
}

The following example uses getResourceURL to parse the Resource Index to find the user profile URL. The data is returned as an AJAX request object (profileRequest).

Example: Retrieving the User Profile

function resourceIndexCallback(data) {
   //get my user profile
   profileRequest.get(
      getResourceURL(data, 'urn:oracle:webcenter:people'),
      profileCallback,
      clearUIBusy);
}

The following example takes the new status message provided by the user in the HTML page (statusMessage) and uses request.put to update the status object (retrieved by again calling getResourceURL).

Example: Retrieving the Status Object

function profileCallback(data) {
   profile = data;
   // get the URL for the status object
   var url = getResourceURL(data, 'urn:oracle:webcenter:people:person:status');
   // get the new status and escape double quotes
   var newStatus = document.getElementById
      ('statusMessage').value.replace(/\"/g. "\\\"");
   //send a JSON string representing the new status object
   var statusMessage = '{"note": "' + newStatus + '"}';
   statusRequest.put(
      getResourceURL(data, 'urn:oracle:webcenter:people:person:status'),
         statusMessage, renderStatusPutResults, clearUIBusy);
}

The renderStatusPutResults method, shown in the example below, renders the new status object.

Example: Rendering the New Status Object

function renderStatusPutResults(data) {
   var name = profile.displayName;
   // get the URL for my profile HTML page in WebCenter Portal
   var profileURL = getResourceURL(profile,
      'urn:oracle:webcenter:spaces:profile');
   var html = 'Status for <a href="' + profileURL + '" target="_blank">'
      + name + '</a> is: ' + data.note;
   // clear the UI busy state and print the new status message
   clearUIBusy(html);
}

The following example shows the code for disabling and reenabling the UI.

Example: Disabling the UI

function setUIBusy(message) {
   document.getElementById('statusResults').innerHTML = message;
   document.getElementById('button1').disabled = true;
   document.getElementById('statusMessage').disabled = true;
}

function clearUIBusy(message) {
   document.getElementById('statusResults').innerHTML = message;
   document.getElementById('button1').disabled = false;
   document.getElementById('statusMessage').disabled = false;
}

The example below shows the library that assists in AJAX calls. Most of this is not WebCenter specific and works for any XHR requests to a service that returns JSON.

The library includes a reusable XHR object. This object supports HTTP GET, POST, PUT, and DELETE. All functions are asynchronous and take a URL and two callback functions, one for success, and one for failure. Success calls are made with a JavaScript object containing the return data. Failure calls are made with an error string. POST and PUT also take a data argument which must be a JSON string.

Example: AJAX Library

function AjaxRequest() {
   // constructor to create an object oriented AJAX request
   var xhr = null;

   // get XHR object. Should work for IE 6+, Safari, and Mozilla based browsers
   if (window.XMLHttpRequest) {
      xhr = new window.XMLHTTPRequest;
   } else {
      try {
         xhr = new ActiveXObject('MSXML2.XMLHTTP.3.0');
      } catch (ex) {
         xhr = null;
      }
   }
   if (xhr == null) {
      alert("Your browser does not support AJAX");
   }

   this.get = function(url, callback, errorCallback) {
      xhr.open('GET', url, true);
      // the REST APIs return XML by default. Please return JSON
      xhr.setRequestHeader('Accept', 'application/json; charset=utf-8');
      sendRequest(null, callback, errorCallback);
   };

   this.post = function(url, data, callback, errorCallback) {
      xhr.open('POST', url, true);
      // set headers to send and receive JSON
      xhr.setRequestHeader('Accept', 'application/json; charset=utf-8');
      xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
      sendRequest(data, callback, errorCallback);
   };

   this.put = function(url, data, callback, errorCallback) {
      xhr.open('PUT', url, true);
      // set headesr to send and receive JSON
      xhr.setRequestHeader('Accept', 'application/json; charset=utf-8');
      xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
      sendRequest(data, callback, errorCallback);
   };

   this.deleteResource = function(url, callback, errorCallback) {
      xhr.open('DELETE', url, true);
      sendRequest(null, callback, errorCallback);
   };

   // set the callbacks and send the request with data, if any
   function sendRequest(data, callback, errorCallback) {
      xhr.onreadystatechange = function () {
         processResponse(xhr, callback, errorCallback);
      };
      xhr.send(data);
   }

   function processResponse(xhr, callback, errorCallback) {
      var data = null;
      // can get called here many times. 4 means really done
      if (xhr.readyState == 4) {
         // let's call any HTTP codes in the 200s success
         if (xhr.status >= 200 && xhr.status <300) {
            // convert response text into a JSON object. This is insecure.
            // data should not be blindly evaluated from the server return.
            // consider using json2.js http://www.JSON.org/js.html
            data = eval('(' + xhr.responseText + ')');
            callback(data);
         } else {
            // we got an error. Format an error string
            data = 'Error: ' + xhr.status + ' ' + xhr.statusText + '<br />'
               + xhr.responseText;
            errorCallback(data);
         }
      }
   }
}

C.14 Using the People Connections REST APIs

This section includes the following topics:

C.14.1 Activity Stream REST API

Use the Activity Stream REST API to browse user application activities in an activity stream. This section provides information about the REST API methods you can use to perform this action.

This section includes the following topics:

C.14.1.1 Activity Stream Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For People Connections, each feature has its own link element. For example, to find the entry point for the People Connections' Activity Stream feature, find the link elements with a resourceType of:

urn:oracle:webcenter:activities:stream

The corresponding href or template element provides the URI entry point, which retrieves application activities for the current user from the Activity Stream. The client sends HTTP requests to this entry point to work with the People Connections' Activity Stream feature.

See Also:

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.14.1.2 Activity Stream Resource Type Taxonomy

When the client has identified the entry point, it can then navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Activity Stream Resource Types.

The resource type taxonomy for the People Connections' Activity Stream feature is:

urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:activity

C.14.1.3 Activity Stream Security Considerations

You must be logged into the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.14.1.4 Activity Stream Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.14.1.4.1 urn:oracle:webcenter:activities:stream

The stream response contains URIs for use in retrieving activities from the Activity Stream.

You can retrieve the activities from a user's stream or activities from a user's connections' streams. To have even greater control over which activities to retrieve, use the activity stream query filter. With the query filter, you can:

Specify the user to query
Include the user's connections' activities in the results
Include activities from portals, including the Home portal, in the results
Restrict the results to activities from specific services

The options available to you depend on the path you take to get to the stream resource and the rel of the link that you use. For example, the activity stream query filter is available only from links with a rel attribute of urn:oracle:webcenter:activities:stream. If you access the activity stream query filter from the person resource, the personGuid parameter is prefilled.

Table C-4 shows the activities returned depending on the rel element of the link.

Table C-4 Activities Returned by stream

rel	Returns
`urn:oracle:webcenter:activities:stream:person`	Activities from the user's stream (`GUID/@self`)^Foot 1
`urn:oracle:webcenter:activities:stream:connections`	Activities from the user's connections' streams (`GUID/@connections`)
`urn:oracle:webcenter:activities:stream`	Activities determined by the activity stream query filter
`urn:oracle:webcenter:activities:stream:space`	Activities from the portal activity stream
`urn:oracle:webcenter:activities:stream:list`	Activities from the portal activity list

^Footnote 1

GUID can be any valid user GUID or @me.

C.14.1.4.2 Navigation Paths to stream

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   stream (rel="urn:oracle:webcenter:activities:stream:person" or
               "urn:oracle:webcenter:activities:stream")

resourceIndex
   person
      stream (rel="urn:oracle:webcenter:activities:stream:person" or
                  "urn:oracle:webcenter:activities:stream:connections" or
                  "urn:oracle:webcenter:activities:stream")

resourceIndex
   person
      list
         stream

resourceIndex
   space
      stream

stream
   activity
      param
         stream (rel="urn:oracle:webcenter:activities:stream:space")

personReference
   stream

C.14.1.4.3 Supported Methods for stream

The following method is supported by the stream resource:

GET
- request—Parameters:
  - startIndex, itemsPerPage
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see Common Request Query Parameters.
  
  The following additional parameters are available for the query filter URI:
  - fromDate – Specifies activities start date (yyyy-mm-dd).
  - toDate – Specifies activities end date, (yyyy-mm-dd).
  - data – Returns specified data only (for more information, see Common Request Query Parameters). For the stream resource, if you specify the constant 'data' as the data parameter, all of the basic information about the resource is returned except "comments" and "likes" summaries. If you want to return comments or likes, specify the data parameter value 'commentsSummary' or 'likesSummary'.
    
    Note:
    
    You can specify multiple data values as a comma separated list. For example, data=data, commentsSummary.
  - personGuid – (Required) Retrieves activities from the stream for the specified user. Valid values: any valid user GUID or @me.
  - serviceIds – Retrieves activities only for the specified services. Valid values: An asterisk (*) returns all services. If null or empty, uses the user preference settings for service filters (from the settings link in the top bar).
  - personal – Includes the specified user's activities in the Home portal. Valid values: true or false. Default value: false.
  - connections – Includes activities from the streams of the specified user's connections. Valid values: true or false. Default value: false.
  - groupSpaces – Includes activities from all portals of which the specified user is a member. Valid values: true or false. Default value: false.
  - connectionListIds – A comma separated list of connection list names that specifies the connection lists used to show activities.
  - groupSpaceGuids – A comma separated list of portal GUIDs used to show activities.
  - userGroupSpaceActivities – Specifies whether or not to show the user's activities in their portal. Valid values: true or false. Default value: false.
  - followedObjects – Specifies whether or not to show all activities for followed objects that both the current user and the specified user follow. Valid values: true or false. Default value: false.
  - followedObjectsUserActivities – Specifies whether or not to show the specified user's activities for followed objects that both the current user and the specified user follow. Valid values: true or false. Default value: false.
  - advancedQuery – Specifies filters against streamed activities. Create filters for user names, service IDs, and object details, such as a document's display name.
    
    Note:
    
    You must plug actual values into the advancedQuery parameter. You cannot pass EL expressions directly into the parameter. Typically, the REST API client handles an EL transformation manually and inserts the actual object data value into the REST URL. See the example below.
  For example, the following URI returns activities from the current user's activity stream, for all services that the user has configured in their personal preference settings for service filters. It returns activities from the user's Home portal and from the streams of the user's connections:
```
http://host:port/rest/api/activities?personal=true&connections=true&personGuid=@me&token=utoken
```
  The following URI returns only the user's personal profile and connections activities:
```
http://host:port/rest/api/activities?serviceIds=oracle.webcenter.peopleconn
ections.profile,oracle.webcenter.peopleconnections.connections&personal=
true&personGuid=@me&token=utoken
```
  This next example illustrates how to use the advancedQuery parameter. As explained previously, you cannot pass an EL expression to advancedQuery. The REST API client must first obtain the actual data object value, and that value can then be passed to advancedQuery. For example, to filter activities for a particular portal, you can pass the GUID of the portal's scope to advancedQuery:
```
http://host:port/rest/api/activities?personGuid=@me&advancedQuery=AE.SCOPE_ID%20%3D%20\%27s8bba98ff_4cbb_40b8_beee_296c916a23ed\%27&ttoken=token
```
  where s8bba98ff_4cbb_40b8_beee_296c916a23ed is the GUID of the portal. Note that the query string must be encoded with the appropriate escape codes.
- response—Body: 0 or more activities
  
  Note:
  
  Because the stream resource includes activity items, the response may also return resource links for the objects referenced in the activity.

C.14.1.4.4 Resource Types Linked to From stream

Table C-5 lists the resource types that the client can link to from the stream resource.

Table C-5 Related Resource Types for stream

rel	resourceType
self urn:oracle:webcenter:activities:stream:person	urn:oracle:webcenter:activities:stream
Related	urn:oracle:webcenter:activities:activity

C.14.1.4.5 urn:oracle:webcenter:activities:activity

The activity response contains the data for activities and URIs for use in retrieving all the data you need from an activity that is included in an Activity Stream.

C.14.1.4.6 Navigation Paths to activity

This section shows how the client can navigate through the hypermedia to access the activity resource:

resourceIndex
   stream
      activity

resourceIndex
   person
      stream
         activity

resourceIndex
   space
      stream
         activity

C.14.1.4.7 Supported Methods for activity

No methods are supported for activity. Activities are currently available only from the stream resource type.

C.14.1.4.8 Resource Types Linked to from activity

Table C-6 lists the resource types that the client can link to from this resource.

Table C-6 Related Resource Types for urn:oracle:webcenter:activities:activity

rel	resourceType
self	`urn:oracle:webcenter:activities:activity`
icon	urn:oracle:webcenter:activities:activity:icon

C.14.1.4.9 Read-only Elements for activity

Table C-7 lists the read-only elements for the activity resource.

Note:

The activity will also return a link to an activity icon in the links section of the response, if an icon is available. See urn:oracle:webcenter:activities:activity:icon.

Table C-7 Read-Only Elements for activity

Element	Type	Description
`activityType`	String	Activity type Unique within the service. For example, Discussions can return the `activityType` `createForum`.
`commentsCount`	String	If you specify `commentsSummary` in the data parameter, then the `commentsCount` parameter will be returned.
`createdDate`	Date (String)^Foot 2	Date the activity was created.
`description`	String	The description of the activity.
`detail`	String	Detail information for the activity, if available. For example, this might return the contents of a message, the file name of a document, and the like. Similar to `detailURL`. Both, either, or neither can be used. The detailURL will be available when creating wiki and blog in a portal.
`detailURL`	String	detailURL is available when creating wikis and blogs in a portal.In a Web-based WebCenter Portal, the user can click this URL and open a wiki or blog page in a portal. Similar to `detail`. Both, either, or neither can be used.
`displayDescription`	String	A pre-formatted, internationalized description.
`displayMessage`	String	A pre-formatted, internationalized message (does not include template information).
`groupSpace`	groupSpaceReference	Information about the portal in which the activity was performed Note: This reference is not present for activities that did not happen in a portal (for example, activities that happened in the Home portal). Also, because creation of a portal happens in a Home portal, that activity does not have this element either.
`id`	String	Unique ID of the message
`isSummary`	true or false	Indicates whether or not this activity is a summary of other activities.
`likesCount`	String	If you specify `likesSummary` in the data parameter, then the `likesCount` parameter will be returned.
`message`	String	Localized string for this activity This may contain replacement strings within curly braces ({}).
`permission`	PRIVATE SHARED PUBLIC	Permission level of this activity
`scope`	String	Scope of the activity This might return a portal, like the Home portal. For example, for a portal, it returns a string similar to the following: s8bba98ff_4cbb_40b8_beee_296c916a23ed
`serviceId`	String	Unique ID of the service that created the activity
`sharedLink_url`	String	Can be used to render a navigation link by the REST client as shown in the example below: <param resourceType="urn:oracle:webcenter:activities:parameter"> <links> <link href="http://www.google.com" /> </links> <displayName>http://www.google.com</displayName> <key>_sharedLink_url</key> <type>custom</type> </param> " Note that this parameter cannot be used in a message template (for example: `{actor[0]}` has created the portal {object[0]}).
`templateParams`	urn:oracle:webcenter:activities:parameter	A list of `param` elements that capture data related to an activity. A key provided with each `templateParam` <param> element allows you to plug one or more data items into a parameterized activity message. See Understanding the templateParams Element.
`custom`	Param	The custom parameter includes a `displayName`, `key`, and `type`, and may or may not have a URL.

^Footnote 2

Data types, such as DATE and BOOLEAN, are stored in the API as STRING. The DATE data type returns a Java standard date format, for example, 2009-08-21T14:43:11.0013-0700, with 0700 representing the time zone.

C.14.1.4.10 Understanding the templateParams Element

Suppose you want to display the most recent messages for a user named Carl. You want to display information like this: "Carl created the portal Customer Feedback". The templateParams element helps you solve this problem.

The templateParams element is returned in objects of type oracle:webcenter:activities:activity. This element captures a lot of data related to an activity. For example, if a user creates a new portal, the templateParams element for that activity captures information about the user and about the portal. Keys are provided that allow you to perform string substitutions in a parameterized message string related to the activity.

For example, if the user creates a portal, the returned activity object contains a <message> item that is parameterized like this:

<message>{actor[0]} has created the portal {object[0]}</message>

By parsing the templateParams element for the activity, you can find the available keys that allow you to perform string substitutions as well as appropriate data to display, like the name of the user and the activity.

The templateParams element also provides links to comments, likes, commentsSummary, and likesSummary objects, if they are requested using the data parameter. These links let you query for all the comments or likes for an object or post a new comment or like. The summary links returns the comments or likes count and several recent comments or likes. See also Understanding Comments and Likes.

The links returned with the templateParams element vary depending on what kind of object is returned, like a user, document, portal, or custom object. For more information, see urn:oracle:webcenter:activities:parameter.

Note:

The templateParams element can sometimes contain elements that are not directly referenced in the message.

If a rel link is marked "via," this means it is a link to the underlying REST object–for instance, the document not the parameter. If a rel link is marked "alternate" and type "text/html," it is a link to the HTML page for that object. Portal objects include an activity stream link for portals. Users have icon and activity stream links. Other objects can have an alt link to the tagged item, as well as the related tagged items list, if tagging is enabled for that object. If a regular object supports comments or likes, it can include the comments/commentsSummary and likes/likesSummary, as explained previously.

C.14.1.4.11 Understanding Comments and Likes

Hyperlinks to comments, commentsSummary, likes and likesSummary are included by default (you can expand the commentsSummary and likesSummary by specifying data=data,commentsSummary,likesSummary). Comments and likes can be associated with the object referenced by the activity or the activity itself. For example, if you edit a document, then the comments will be associated with the document. If you add comments on an edit document activity on the activity stream page, then comments will be associated with the edit document activity.

The links associated with comments and likes are:

comments – The comments link lets you query for all the comments for an object. This link also lets you POST a new comment. For a comments POST, the text field is required. For example, for body data you would use:

JSON:
```
           {
             "text" : "REST Comment"
           }
```
XML:
```
           <text>REST Comment</text> 
```
commentsSummary – The commentsSummary link returns the comments count and several recent comments.
likes – The likes link lets you query for all the likes for an object. This link also lets you POST a new like. There are no required fields for a likes POST.
likesSummary – The likesSummary link returns the likes count and the current user's like (if available).

Note:

Like objects themselves only support DELETE, not GET. The likesCount and commentsCount items return the number of likes or comments for the current object.

The following URLs show examples of GET requests for comments, commentSummary, likes and likesSummary for a document object:

"http://example.com:8892/rest/api/activities/services/oracle.webcenter.doclib/objectTypes/document/objects/(<document_object_id>)/comments?startIndex=0&amp;itemsPerPage=10&amp;utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

"http://example.com:8892/rest/api/activities/services/oracle.webcenter.doclib/objectTypes/document/objects/(<document_object_id>)/commentsSummary?utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

"http://example.com:8892/rest/api/activities/services/oracle.webcenter.doclib/objectTypes/document/objects/(<document_object_id>)/likes?startIndex=0&amp;itemsPerPage=10&amp;utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

"http://example.com:8892/rest/api/activities/services/oracle.webcenter.doclib/objectTypes/document/objects/(<document_object_id>)/likesSummary?utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

Where <document_object_id> is the document object ID.

The following URLs show examples of GET requests for comments, commentSummary, likes and likesSummary for a create document activity:

"http://example.com:8892/rest/api/activities/ffa9a9f0-d02f-4e30-8c58-8a41b7a6e8a3/comments?startIndex=0&amp;itemsPerPage=10&amp;utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

"http://example.com:8892/rest/api/activities/ffa9a9f0-d02f-4e30-8c58-8a41b7a6e8a3/commentsSummary?utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

"http://example.com:8892/rest/api/activities/ffa9a9f0-d02f-4e30-8c58-8a41b7a6e8a3/likes?startIndex=0&amp;itemsPerPage=10&amp;utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"
                  "http://example.com:8892/rest/api/activities/ffa9a9f0-d02f-4e30-8c58-8a41b7a6e8a3/likesSummary?utoken=FCvY3qQSBh0eAByLdxugV-lUgFO3_w**"

C.14.1.4.12 urn:oracle:webcenter:activities:parameter

The templateParams element returns a set of param elements. The param elements return data specific to the type of activity object returned. The possible types of param elements include:

user – Returns the displayName, guid, id, key, primaryId, and type.
document – Returns the displayName, iconUrl, id, key, primaryId, and type.
custom – Returns displayName, key, and type, and may or may not have a URL.

A param can also be a variable reference or key of the general form {prefix[index].variable}.

C.14.1.4.13 urn:oracle:webcenter:activities:activity:icon

Use this resource type to get the icon of the activity, if available (GET).

C.14.1.4.14 Navigation Paths to activities:activity:icon

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   activities
      activity
         icon

C.14.1.4.15 Supported Methods for icon

The following methods are supported by this resource:

GET – Returns the icon used for the named activity.

C.14.1.4.16 Resource Types Linked to from icon

Table C-8 lists the resource types that the client can link to from this resource.

Table C-8 Related Resource Types for urn:oracle:webcenter:activities:activity:icon

rel	resourceType
self
urn:oracle:webcenter:parent	`urn:oracle:webcenter:activities:activity`

C.14.2 Connections and Profile REST API

Use the Connections and Profile REST API to browse a profile or a connections list, manage connections lists, add or remove connections, send invitations to connect, and update a profile status message. This section provides information about the REST API methods to use to perform these actions.

This section includes the following topics:

C.14.2.1 Connections and Profile Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For People Connections, each feature has its own link element. For example, to find the entry points for the People Connections' Connections and Profile features, find the link elements with a resourceType of:

urn:oracle:webcenter:people (returns the current user profile)

urn:oracle:webcenter:people:person (enables you to query for a user)

urn:oracle:webcenter:people:invitations (returns invitations sent or received by the current user)

Note:

The people:person and people:invitations resource types have a template but not an href.

The corresponding href or template element provides the URI entry point, which returns a list of people (people) or an individual user (people:person). The client sends HTTP requests to this entry point to work with the People Connections' Connections and Profile features.

C.14.2.2 Connections and Profile Resource Type Taxonomy

The resource type taxonomy for the People Connections' Connections and Profile features is:

urn:oracle:webcenter:people
   urn:oracle:webcenter:people:person
   urn:oracle:webcenter:people:icon
   urn:oracle:webcenter:people:person:list
      urn:oracle:webcenter:people:person:listNames
      urn:oracle:webcenter:people:person:listName
      urn:oracle:webcenter:people:person:list:member
      urn:oracle:webcenter:people:person:status
   urn:oracle:webcenter:people:invitations
      urn:oracle:webcenter:people:invitation

C.14.2.3 Connections and Profile Security Considerations

You must be logged in to the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

C.14.2.4 Connections and Profile Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.14.2.4.1 urn:oracle:webcenter:people

The people response contains URIs for use in retrieving the profile of one or more users.

C.14.2.4.2 Navigation Paths to people

This section shows how the client can navigate through the hypermedia to access the people resource:

resourceIndex
   people

C.14.2.4.3 Supported Methods for people

The following method is supported by the people resource:

GET
- request—Parameters:
  - startIndex – See Common Request Query Parameters.
  - itemsPerPage – See Common Request Query Parameters.
  - projection – See Common Request Query Parameters.
  - data – The data parameter is a comma separated list that controls which data will be returned in the response. The predefined set basic is equivalent to data=guid,id,displayName. The predefined set data is a standard set that returns all the data for the user, but does not include status, manager, reportees, or photos. The full list of possible values includes the predefined sets basic and data, as well as the following individual data values: guid, id, displayName, birthday, language, timeZone, name, addresses, organizations, workEmail, phoneNumbers, manager, reportees, photos, and status.
    
    If you specify the constant 'data' as the data parameter, all the basic information will be returned for the resource. If both the projection and data query string parameters are present, the data parameter will be used to determine which data to return.
    
    The data parameter can also take any of the following values comma-separated values to return the corresponding data: guid, id, displayName, birthday, language, timeZone, name, addresses, organizations, workEmail, phoneNumbers, manager, reportees, photos, and/or status.
    
    Note:
    
    The data parameter can accept a predefined set, a collection of values, or a mix of sets and values. For example, to get the basic data plus the user's birthday, you can specify data=basic,birthday.
  - links – The links parameter is a comma-separated list that controls which links will be returned in the response. This parameter can accept predefined sets, individual data values, or a combination of predefined sets and individual data values. The predefined sets are basic, data, activitiesSet, connectionsSet, and feedbackSet. These predefined sets are described in Predefined Sets for the links Parameter.
    
    The individual values for the links parameter are: person, profile, icon, status, messageBoard, activities, personActivities, connectionActivities, connections, listNames, invitation, givenFeedback, receivedFeedback, userGivenFeedback, manager, reportees, member.
    
    If both the projection and links query string parameters are present, the links parameter will be used to determine which links to return.
- response—Body: One or more person objects.

C.14.2.4.4 Predefined Sets for the links Parameter

The following items are predefined sets that can be returned in the links parameter. For example, if you specify links=basic, it is the equivalent of specifying data=person,profile,icon. You can also specify additional parameters as needed. For example, you could specify data=basic,birthday.

Note:

Links that are not currently available will not be returned even if they are specified in the links parameter.

basic – A standard set that returns the basic information for the profile and includes person, profile, and icon.
data – A standard set that returns all the basic links for the response plus the connections list, status, and activity stream template.
activitiesSet – Includes activities, personActivities, and connectionActivities.
connectionsSet – Includes connections, listNames, and invitation.
feedbackSet – Includes givenFeedback, receivedFeedback, and userGivenFeedback.

C.14.2.4.5 Resource Types Linked to from people

Table C-9 lists the resource types that the client can link to from the people resource.

Table C-9 Related Resource Types for people

rel	resourceType
urn:oracle:webcenter:people:icon	urn:oracle:webcenter:people:person
urn:oracle:webcenter:people:person:list:connections	urn:oracle:webcenter:people:person:list
urn:oracle:webcenter:activities:stream:person	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream:connections	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:feedback:all-received	urn:oracle:webcenter:feedback
urn:oracle:webcenter:feedback:all-given	urn:oracle:webcenter:feedback
self	urn:oracle:webcenter:people:person:status
urn:oracle:webcenter:people:person:list:list	urn:oracle:webcenter:people:person:list
self	urn:oracle:webcenter:people:person:listName
urn:oracle:webcenter:activities:stream:list	urn:oracle:webcenter:activities:stream

C.14.2.4.6 urn:oracle:webcenter:people:icon

Use this resource type to get the icon used for the named profile (GET).

Navigation Paths to people:icon

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   people
      icon

C.14.2.4.7 Supported Methods for icon

The following methods are supported by this resource:

GET – Returns the icon used for the named profile.

Note:

This resource includes a template that lets you choose the size of the profile icon to use. The size template parameter can be set to small, medium, or large.

C.14.2.4.8 Resource Types Linked to from icon

Table C-10 lists the resource types that the client can link to from this resource.

Table C-10 Related Resource Types for urn:oracle:webcenter:people:icon

rel	resourceType
self	`urn:oracle:webcenter:people:icon`
urn:oracle:webcenter:parent	`urn:oracle:webcenter:people`

C.14.2.4.9 urn:oracle:webcenter:people:person

The person response contains profile data and the URIs for use in retrieving a user profile.

C.14.2.4.10 Navigation Paths to person

This section shows how the client can navigate through the hypermedia to access the person resource:

resourceIndex
   people

resourceIndex
   people
      person

resourceIndex
   person

author
   person

resourceIndex
   activities:stream
      person

C.14.2.4.11 Supported Methods for person

The following method is supported by the person resource:

GET
- request—Parameters: q
  
  To retrieve a specified person, the format of q is:
```
q=[loginid:equals:username]
Or
q=[guid:equals:guid]
Or
q=[email:equals:email]
```
  Note:
  
  The parameter q is only on the resourceIndex template for person.
- response—Body: message
  
  See Also:
  
  For information about the response message, see Read-only Elements for person.

C.14.2.4.12 Read-only Elements for person

Table C-11 lists the read-only elements for the person resource.

Note:

The elements present in a person response depend on how the user repository is configured and the elements it supports. Additionally, several of the pieces of data represented in Table C-11, such as address, emails, photos, phoneNumbers, and organization, can have multiple instances.

See Also:

Some of the elements listed in Table C-11 can be returned in predefined sets described in Predefined Sets for the links Parameter.

Table C-11 Read-Only Elements for person

Element	Type	Description
`guid`	String	Unique GUID of the person
`id`	String	Unique login ID of the person (that is, the user name, for example, pat_coi)
`displayName`	String	Display name of the person (the user's name, for example, Pat Coi). This may have the same value as `id`, depending on the repository configuration.
`birthday`	Date (String)^Foot 3	Birth date of the person
`connected`	Boolean (String)1	Whether or not this person is connected to the current user
`language`	String	Preferred language of the person
`timeZone`	String	Time zone of the person
`name`	`name`	Name information for the person `name` is a portable contact type. For more information, see name Portable Contact Type.
`address`	`address`	Address information for the person address is a portable contact type. For more information, see address Portable Contact Type.
`emails`	`value`	Emails for the person `emails` is derived from the `value` portable contact type. For more information, see value Portable Contact Type.
`photos`	`value`	Profile photos for the person `photos` is derived from the `value` portable contact type. For more information, see value Portable Contact Type.
`phoneNumbers`	`value`	Phone numbers for the person `phoneNumber` is derived from the `value` portable contact type. For more information, see value Portable Contact Type.
`organizations`	`organization`	Organization information for the person organization is a portable contact type. For more information, see organization Portable Contact Type
`manager`	personReference	Manager of this person
`reportees`	personReference	Direct reports of this person
`status`	urn:oracle:webcenter:people:person:status	Person's profile status message

^Footnote 3

Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

C.14.2.4.13 Resource Types Linked to from person

Table C-12 lists the resource types that the client can link to from the person resource.

Table C-12 Related Resource Types for person

rel	resourceType
self	urn:oracle:webcenter:people:person
alternate	urn:oracle:webcenter:spaces:profile (HTML)
urn:oracle:webcenter:people:person:list:connections	urn:oracle:webcenter:people:person:list
Related	urn:oracle:webcenter:people:person:listNames
Related	urn:oracle:webcenter:people:person:status
urn:oracle:webcenter:activities:stream:person	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream:connections	urn:oracle:webcenter:activities:stream
urn:oracle:webcenter:activities:stream	urn:oracle:webcenter:activities:stream
Related	urn:oracle:webcenter:messageBoard
urn:oracle:webcenter:feedback:all-given	urn:oracle:webcenter:feedback
urn:oracle:webcenter:feedback:all-received	urn:oracle:webcenter:feedback

C.14.2.4.14 urn:oracle:webcenter:people:person:list

The list response contains URIs for use in retrieving all the profiles on a connections list (GET), inviting a user to be a connection or adding a connection to a connections list (POST), and removing a connections list (DELETE).

C.14.2.4.15 Navigation Paths to list

This section shows how the client can navigate through the hypermedia to access the list resource:

resourceIndex
   person
      listNames
         list

resourceIndex
   person
      list (rel="urn:oracle:webcenter:people:person:list:connections")

C.14.2.4.16 Supported Methods for list

The following methods are supported by the list resource:

GET
- request—Parameters: startIndex, itemsPerPage, projection
  
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see Common Request Query Parameters.
- response—Body: 0 or more person items
POST
- request—Body: member
- response—Body: member
See Also:

For information about member in the request and response elements, see urn:oracle:webcenter:people:person:list:member.
DELETE
- request

C.14.2.4.17 Resource Types Linked to from list

Table C-13 lists the resource types that the client can link to from the list resource.

Table C-13 Related Resource Types for list

rel	resourceType
self urn:oracle:webcenter:people:person:list^Foot 4	urn:oracle:webcenter:people:person:list
urn:oracle:webcenter:activities:stream	urn:oracle:webcenter:activities:stream

^Footnote 4

self rel currently includes "urn:oracle:webcenter:people:person:list:list" instead of the correct "urn:oracle:webcenter:people:person:list". For the @connections default list, it currently includes "urn:oracle:webcenter:people:person:list:connections".

C.14.2.4.18 urn:oracle:webcenter:people:person:listNames

The listNames response contains the names of existing connections lists as well as the URIs for use in retrieving the lists (GET) and creating connections lists (POST).

C.14.2.4.19 Navigation Paths to listNames

This section shows how the client can navigate through the hypermedia to access the listNames resource:

resourceIndex
   person
      listNames

C.14.2.4.20 Supported Methods for listNames

The following methods are supported by the listNames resource:

GET
- request
- response: Body: 0 or more listName items
POST
- request—Body: listName
- response—Body: listName

See Also:

For information about listName, see urn:oracle:webcenter:people:person:listName.

C.14.2.4.21 Resource Types Linked to from listNames

Table C-14 lists the resource types that the client can link to from the listNames resource.

Table C-14 Related Resource Types for listNames

rel	resourceType
self	urn:oracle:webcenter:people:person:listNames

C.14.2.4.22 urn:oracle:webcenter:people:person:listName

The listName response contains the names of connections lists and URIs for use in accessing the connections lists. See also urn:oracle:webcenter:people:person:listName.

C.14.2.4.23 Navigation Paths to listName

This section shows how the client can navigate through the hypermedia to access the listName resource:

resourceIndex
   person
      listNames
         listName

C.14.2.4.24 Supported Methods for listName

The following method is supported by the listName resource:

DELETE
- request

C.14.2.4.25 Writable Elements for listName

Table C-15 lists the writable elements for the listName resource.

Table C-15 Writable Elements for listName

Element	Type	Required	Constraints	Description
`name`	String	Yes	1 or more characters	A single list name

C.14.2.4.26 Resource Types Linked to from listName

Table C-16 lists the resource types that the client can link to from the listName resource.

Table C-16 Related Resource Types for listName

rel	resourceType
self urn:oracle:webcenter:people:person:list	urn:oracle:webcenter:people:person:list
urn:oracle:webcenter:activities:stream:list	urn:oracle:webcenter:activities:stream

C.14.2.4.27 urn:oracle:webcenter:people:person:list:member

The member response contains URIs for use in deleting a connection from a connections list.

C.14.2.4.28 Navigation Paths to member

This section shows how the client can navigate through the hypermedia to access the member resource:

resourceIndex
   person
      list
         member

C.14.2.4.29 Supported Methods for member

The following method is supported by the member resource:

DELETE
- request

C.14.2.4.30 Writable Elements for member

Table C-17 lists the writable elements for the member resource. Writable elements for member are used when you add a connection to a list or invite a user to be a connection. The member resource itself is for deleting connections, and does not use writable elements.

Table C-17 Writable Elements for member

Element Type Required Constraints Description

Element	Type	Required	Constraints	Description
`guid`	String	Yes	1 or more characters	GUID of the user
`message`	String	No	0 or more characters	Invitation message Use this only when inviting users to be connections (that is POSTing to the `@connections` list, not to user-created connections lists).

guid

String

Yes

1 or more characters

GUID of the user

message

String

0 or more characters

Invitation message

Use this only when inviting users to be connections (that is POSTing to the @connections list, not to user-created connections lists).

C.14.2.4.31 urn:oracle:webcenter:people:person:status

The status response contains URIs for use in retrieving (GET) and updating (PUT) the profile status message of a specified user.

C.14.2.4.32 Navigation Paths to status

This section shows how the client can navigate through the hypermedia to access the status resource:

resourceIndex
   people
      person
         status

C.14.2.4.33 Supported Methods for status

The following methods are supported by the status resource:

GET
- request
- response—Body: status
PUT
- request—Body: status
- response—Body: status

C.14.2.4.34 Writable Elements for status

Table C-18 lists the writable elements for the status resource.

Table C-18 Writable Elements for status

Element	Type	Required	Constraints	Description
`note`	String	Yes	1 or more characters	Content of status message

C.14.2.4.35 Resource Types Linked to from status

Table C-19 lists the resource types that the client can link to from the status resource.

Table C-19 Related Resource Types for status

rel	resourceType
self	urn:oracle:webcenter:people:person:status

C.14.2.4.36 urn:oracle:webcenter:people:invitations

The invitations response contains URIs for use in retrieving invitations (GET). You can also send an invitation (POST) to another user.

C.14.2.4.37 Navigation Paths to invitations

This section shows how the client can navigate through the hypermedia to access the invitations resource:

resourceIndex
   invitations

If you are not already connected to a user, you can also navigate to the invitations resource from that user's profile in order to invite them to connect. This path is only used for POSTing.

resourceIndex
   person
      invitations

C.14.2.4.38 Supported Methods for invitations

The following methods are supported by the invitations resource:

GET
- Request—Parameters: q
  
  To retrieve invitations sent to the current user, the format of q is:
```
q=[invitee:equals:@me]
```
  To retrieve invitations sent from the current user, the format of q is:
```
q=[invitor:equals:@me]
```
- Response—Body: 1 or more invitations
POST
- Request—Body: invitation
- Response—Body: invitation

C.14.2.4.39 Writable Elements for invitations

Table C-20 lists the writable elements for the invitations resource.

Table C-20 Writable Elements for invitations

Element	Type	Required	Constraints	Description
`message`	String	No	1 or more characters	Message attached to the invitation

C.14.2.4.40 Resource Types Linked to from invitations

Table C-21 lists the resource types that the client can link to from the invitations resource:

Table C-21 Related Resource Types for invitations

rel	resourceType
self	urn:oracle:webcenter:people:invitation

C.14.2.4.41 urn:oracle:webcenter:people:invitation

The invitation response contains URIs for use in deleting (DELETE) invitations you have sent, or deleting (DELETE) or updating (PUT) invitations you have received.

C.14.2.4.42 Navigation Paths to invitation

This section shows how the client can navigate through the hypermedia to access the invitation resource:

resourceIndex
   invitations
      invitation

C.14.2.4.43 Supported Methods for invitation

The following methods are supported by the invitation resource:

PUT
- Request—Body: invitation
- Response—Body: invitation
DELETE
- Request

C.14.2.4.44 Writable Elements for invitation

Table C-22 lists the writable elements for the invitation resource.

Table C-22 Writable Elements for invitation

Element Type Required Constraints Description

Element	Type	Required	Constraints	Description
`status`	String	Yes (PUT)	ACCEPTED IGNORED	The status of the invitation. Note: When you accept or ignore an invitation, it is removed from your list of invitations.

status

String

Yes (PUT)

ACCEPTED

IGNORED

The status of the invitation.

Note: When you accept or ignore an invitation, it is removed from your list of invitations.

C.14.2.4.45 Read-only Elements for invitation

Table C-23 lists the read-only elements for the invitation resource.

Table C-23 Read-only Elements for invitation

Element	Type	Description
`id`	String	Unique ID of the invitation
`invitee`	personReference	User to whom the invitation is sent
`invitor`	personReference	User from whom the invitation is sent
`sentDate`	Date (String)^Foot 5	Date the invitation was sent

^Footnote 5

Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

C.14.2.4.46 Resource Types Linked to from invitation

Table C-24 lists the resource types that the client can link to from the invitation response.

Table C-24 Related Resource Types for invitations

rel	resourceType
self	urn:oracle:webcenter:people:invitation

C.14.3 Feedback REST API

Use the Feedback REST API to read and delete feedback. This section provides information about the REST API methods to use to perform these actions.

This section includes the following topics:

C.14.3.1 Feedback Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For People Connections, each feature has its own link element. To find the entry points for the People Connections' Feedback feature, find the link elements with a resourceType of:

urn:oracle:webcenter:feedback

The corresponding href or template element provides the URI entry point, which returns all received feedback for the current user. The client sends HTTP requests to this entry point to work with the People Connections' Feedback feature.

See Also:

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.14.3.2 Feedback Resource Type Taxonomy

The resource type taxonomy for the People Connections' Feedback feature is:

urn:oracle:webcenter:feedback
   urn:oracle:webcenter:feedback:message

C.14.3.3 Feedback Security Considerations

You must be logged into the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.14.3.4 Feedback Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.14.3.4.1 urn:oracle:webcenter:feedback

The feedback response contains URIs for use in reading Feedback messages.

C.14.3.4.2 Navigation Paths to feedback

This section shows how the client can navigate through the hypermedia to access the feedback resource:

resourceIndex
   feedback

resourceIndex
   person
      feedback

C.14.3.4.3 Supported Methods for feedback

The following methods are supported by the feedback resource:

GET
- request—Parameters: startIndex, itemsPerPage
  
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see Common Request Query Parameters.
- response—Body: message
  
  See Also:
  
  For information about message, see urn:oracle:webcenter:feedback:message.
POST – If permitted, lets you add feedback for a target user. This method is only available if the current user is connected to and has permission to add feedback for the target user.
- request - body: feedback
```
<message resourceType="urn:oracle:webcenter:feedback:message">
    <body>test from REST API</body>
    <receivedUser>
    <guid>4F16DD80393611DFBF895F177662C511</guid>
    </receivedUser>
</message>
```

C.14.3.4.4 Resource Types Linked to from feedback

Table C-25 lists the resource types that the client can link to from the feedback resource.

Table C-25 Related Resource Types for feedback

rel	resourceType
self urn:oracle:webcenter:feedback:all-received	urn:oracle:webcenter:feedback
self urn:oracle:webcenter:feedback:all-given	urn:oracle:webcenter:feedback
NA	urn:oracle:webcenter:feedback:message

C.14.3.4.5 urn:oracle:webcenter:feedback:message

The message response contains the feedback message data and URIs for use in deleting a Feedback message.

C.14.3.4.6 Navigation Paths to message

This section shows how the client can navigate through the hypermedia to access the message resource:

resourceIndex
   feedback
      message

resourceIndex
   person
      feedback
         message

C.14.3.4.7 Supported Methods from message

The following method is supported by the message resource:

DELETE
- request

C.14.3.4.8 Read-only Elements for message

Table C-26 lists the read-only elements for the message resource.

Table C-26 Read-only Elements for message

Element	Type	Description
`body`	String	Message content
`id`	String	Unique ID of the message
`author`	personReference	User who created the message
`created`	Date (String)^Foot 6	Date the message was created
receivedUser	personReference	A person reference to the user who received the feedback

^Footnote 6

Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

C.14.3.4.9 Resource Types Linked to from feedback

Table C-27 lists the resource types that the client can link to from the feedback resource.

Table C-27 Related Resource Types for message

rel	resourceType
self	urn:oracle:webcenter:feedback:message

C.14.4 Message Board REST API

Use the Message Board REST API to post, read, and delete messages to a user's or a portal message board. This section provides information about the REST API methods to use to perform these actions.

This section includes the following topics:

C.14.4.1 Message Board Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For People Connections, each feature has its own link element. To find the entry points for the People Connections' Message Board feature, find the link elements with a resourceType of:

urn:oracle:webcenter:messageBoard

Note:

As well as an entry point from the Resource Index, to navigate to an individual user's message board, the Message Board feature also has an entry point from a portal response for the portal message board.

The corresponding href or template element provides the URI entry point, which returns the Message Board for the current user. The client sends HTTP requests to this entry point to work with People Connections' Message Board feature.

See Also:

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.14.4.2 Message Board Resource Type Taxonomy

The resource type taxonomy for the Message Board feature for People Connections is:

urn:oracle:webcenter:messageBoard
   urn:oracle:webcenter:messageBoard:message

C.14.4.3 Message Board Security Considerations

You must be logged into the REST service to access any of the People Connections REST APIs. After that, the underlying service handles permission checking and the like.

See Also:

For general security considerations, see Security Considerations for WebCenter Portal REST APIs

C.14.4.4 Message Board Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.14.4.4.1 urn:oracle:webcenter:messageBoard

The messageBoard response contains URIs for use in reading (GET) and posting (POST) portal and individual user Message Board messages.

C.14.4.4.2 Navigation Paths to messageBoard

This section shows how the client can navigate through the hypermedia to access the messageBoard resource:

resourceIndex
   messageBoard

resourceIndex
   person
      messageBoard

resourceIndex
   spaces
      space
         messageBoard

C.14.4.4.3 Supported Methods for messageBoard

The following methods are supported by the messageBoard resource:

GET
- request—Parameters: startIndex, itemsPerPage
  
  See Also:
  
  For information about REST API parameters, such as startIndex and itemsPerPage, see Common Request Query Parameters.
- response—Body: message
Note:

The REST GET command for reading (retrieving) messages retrieves all shown messages by default. You can also retrieve messages that are private or hidden through the application user interface as described in Filtering Messages Based on Visibility. For information about hiding and showing messages, see "Adding Messages and Feedback to a Portal" in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal.
POST
- request—Body: message
  
  The POST for messages supports including a link URL in the message.
  
  See Also:
  
  For information about message, see urn:oracle:webcenter:messageBoard:message.

C.14.4.4.4 Read-only Elements for messageBoard

Table C-28 lists the read-only elements for the messageBoard resource.

Table C-28 Read-only Elements for message

Element	Type	Description
`messageType`	String	Returns `link` if the message has a link. Otherwise, returns `null`.
`link`	String	Contains link data for messages with links: `name`, `url`, `icon`, `description`, `mimeType`, `objectId`, `objectType`, `serviceId`.

C.14.4.4.5 Resource Types Linked to from messageBoard

Table C-29 lists the resource types that the client can link to from the messageBoard resource.

Table C-29 Related Resource Types for messageBoard

rel	resourceType
self	urn:oracle:webcenter:messageBoard
NA	urn:oracle:webcenter:messageBoard:message

C.14.4.4.6 urn:oracle:webcenter:messageBoard:message

The message response contains the Message Board message data and URIs for use in reading (GET), revising (PUT), and deleting (DELETE) a portal or individual user Message Board message.

C.14.4.4.7 Navigation Paths to message

This section shows how the client can navigate through the hypermedia to access the message resource:

resourceIndex
   messageBoard
      message

resourceIndex
   person
      messageBoard
         message

resourceIndex
   spaces
      space
         messageBoard
            message

C.14.4.4.8 Supported Methods for message

The following methods are supported by the message resource:

GET
- request
- response—Body: message
PUT
- request—Body: message
- response—Body: message
DELETE
- request

C.14.4.4.9 Writable Elements for message

Table C-30 lists the writable elements for the message resource.

Table C-30 Writable Elements for message

Element	Type	Required	Constraints	Description
`body`	String	Yes	1 or more characters	message content

C.14.4.4.10 Read-only Elements for message

Table C-31 lists the read-only elements for the message resource.

Table C-31 Read-only Elements for message

Element	Type	Description
`id`	String	Unique ID of the message
`author`	personReference	User who created the message
`created`	Date (String)^Foot 7	Date the message was created

^Footnote 7

Data types, such as DATE and BOOLEAN, are stored in the API as STRING.

C.14.4.4.11 Resource Types Linked to from message

Table C-32 lists the resource types that the client can link to from the message resource.

Table C-32 Related Resource Types for message

rel	resourceType
self	urn:oracle:webcenter:messageBoard:message

C.14.4.5 Filtering Messages Based on Visibility

Although the REST GET command for retrieving messages retrieves all shown messages by default, you can also retrieve messages that are private or hidden through the application user interface using a set of visibility filters.

Messages posted on message boards can have the following visibility criteria:

Public
Private
Hidden
Public and hidden
Private and hidden

By default, messages are public.

C.14.4.5.1 Private Messages:

A person owning a message board can mark any message as private. When a message is marked as private, that message will not be visible to anyone other than the owner of the message unless the owner chooses to send a private message to someone else. Otherwise, other people viewing a message board with private messages will see only public messages.

C.14.4.5.2 Hidden Messages:

A person owning a message board can mark any message as hidden. When a message is marked as hidden, that message will not be visible to the owner of the message board, but will remain visible to other people viewing the message board.

C.14.4.5.3 REST URLs for Message Boards:

The context for message board URL filters is:

rest/api/messageBoards/<BOARD-TYPE>/<GUID>/<FILTER-TYPE>

Where:

<BOARD-TYPE> is either person or space
<GUID > is either @me, the person <GUID> (if <BOARD-TYPE> is person) or the space <GUID> (if <BOARD-TYPE> is portal)
<FILTER-TYPE> is applicable only for the person <BOARD-TYPE> and can be one of:
- null - (default) shows all messages
- private - shows private messages
- public - shows public messages
- hidden - shows hidden and public messages
- private_hidden - shows private and hidden messages

Available filters in the context of the applicable HTML methods are shown below.

GET

@me
- all rest/api/messageBoards/person/@me
- private rest/api/messageBoards/person/@me/private
- public rest/api/messageBoards/person/@me/public
- hidden and public rest/api/messageBoards/person/@me/hidden
- private and hidden rest/api/messageBoards/person/@me/private_hidden
person

rest/api/messageBoards/person/<GUID>

If the GUID matches that of the logged in user then the same filtering as for @me applies. If the GUID is different, then no filtering is available.
space

rest/api/messageBoards/space/<GUID>

No filtering based on visibility is available.

POST

@me

all rest/api/messageBoards/person/@me

private

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "private"}

public

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "public"}

hidden and public

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "hidden"}

private and hidden

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "private_hidden"}

person rest/api/messageBoards/person/<GUID> If the GUID is the same as the logged in user, then the filters for GET apply. If the users are different, then the following filters apply:
- public
```
{"body" : "<BODY_CONTENT>",
 "visibilityType" : "public"}
```
- private
```
{"body" : "<BODY_CONTENT>",
 "visibilityType" : "private"}
```
space

rest/api/messageBoards/space/<GUID>

No filtering based on visibility is available.

PUT

@me

all est/api/messageBoards/person/@me/messages/<msg guid>

private

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "private"}

public

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "public"}

hidden and public

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "hidden"}

private and hidden

{"body" : "<BODY_CONTENT>",
 "visibilityType" : "private_hidden"}

person rest/api/messageBoards/person/<GUID>/messages/<msg guid> If the GUID is the same as the logged in user, then the filters for GET apply. If the users are different, then the following filters apply:
- public
```
{"body" : "<BODY_CONTENT>",
 "visibilityType" : "public"}
```
- private
```
{"body" : "<BODY_CONTENT>",
 "visibilityType" : "private"}
```
space

rest/api/messageBoards/space/<GUID>/messages/<msg guid>

No filtering based on visibility is available.

C.14.5 Creating an Invitation

This section illustrates how to invite another user to join your connections list using the People Connections Service REST API. After the invitation is made, the invitee is given the option to accept or not. This example also illustrates how to delete an invitation.

This section includes the following topics:

C.14.5.1 Creating an Invitation

The first step, as always with REST API methods, is to retrieve the resource index:
```
GET http://<host:port>/rest/api/resourceIndex
```
Next, find the person to whom you want to connect. To do this:
1. In the resource index listing, scan for the link with the following resource type:
```
urn:oracle:webcenter:people:person
```
2. Execute a search for the user who you wish to invite. In this example, the user is named Monty.
```
GET http://<host:port>/rest/api/people?q=loginid:equals:monty&utoken=ASDF
```
3. Locate Monty's GUID in the response, as shown in Figure C-2.
  
  Figure C-2 Response With User's GUID
  
  Description of "Figure C-2 Response With User's GUID"
4. Save the GUID so that you can use it to connect to the user.
Now that you have the invitee's GUID, you must find the resource to which you would like to add him. In this case, you want to add him to your own connections list.

To find your connections list, first, scan these People Connections topics for "connections." You will discover in Table C-12 that connections are linked to from the person resource. For convenience, this table is shown in Figure C-3.

Figure C-3 Finding the connections Link

Description of "Figure C-3 Finding the connections Link"

Now that you know that connections are linked to from the person resource, you need to find the person resource. As the URN indicates, you get to the person resource from the people resource, as described in the following steps.
Return to the resource index (or use a cached version of the resourceIndex from your previous visit):
```
GET http://<host:port>/rest/api/resourceIndex
```
Scan for the people resource, and you will find:
```
urn:oracle:webcenter:people
```

Use the link in the people resource to access your lists:

GET http://<host:port>/rest/api/people/@me/lists/@self?utoken=ASDF

Scan the returned links for the resourceType and rel listed in Table C-12:

resourceType="urn:oracle:webcenter:people:person:list
rel="urn:oracle:webcenter:people:person:list:connections

Make the invitation by using the URI to your connections list to execute a POST:

POST http://<host:port>/rest/api/people/@me/lists/@connections?utoken=ASDF
 
Headers --  Accept:application/json, Content-Type:application/json
Body -- {"message":"Monty, do you want to join my connections list?","guid":"1AE5AF102E2611E09F062B573E287934"}

Now, if you log in to Monty's account and you can see the invitation has been added, as shown in Figure C-4.

Figure C-4 Activity Stream Showing Invitation

Description of "Figure C-4 Activity Stream Showing Invitation"

C.14.5.2 Accepting an Invitation

After an invitation has been sent, the next step is for the invitee (Monty) to accept the invitation.

Using a second REST client, retrieve the resource index:
```
GET http://<host:port>/rest/api/resourceIndex
```
Login as Monty.

List all the invitations sent to Monty by making the following request:

GET http://<host:port>/rest/api/people/invitations?q=invitee:equals:@me&utoken=ASDF

Each invitation element listed in the response contains a link that supports the UPDATE operation and that looks something like this:

<links>
<link capabilities="urn:oracle:webcenter:delete urn:oracle:webcenter:update"
href="http://<host:port>/rest/api/people/invitations/<invitationid>?utoken=ASDF"
rel="self" resourceType="urn:oracle:webcenter:people:invitation"/>
</links>
<id><invitationid></id>

To accept the invitation, make the following request:

PUT http://<host:port>/rest/api/people/invitations/<invitationid>?utoken=ASDF

Headers
  Accept -> application/xml
  Content-Type -> application/xml
 
Body
  <invitation>
      <id><invitationid></id>
      <status>accepted</status>
  </invitation>

C.14.5.3 Deleting an Invitation

After you initiate an invitation, you can view the invitation from your account by specifying invitor:equals:@me. For example:

GET http://<host:port>/rest/api/people/invitations?q=invitor:equals:@me&utoken=ASDF

Each invitation element listed in the response contains a link that supports the DELETE operation and that looks something like this:

<links>
<link resourceType="urn:oracle:webcenter:people:invitation" 
rel="self"
href="http://host_name:port_name/rest/api/people/invitations/
   e9073cdb-56ab-423d-8b1f-1220c802bdd4?
   utoken="FN0SEFwX42OCntwtx9a1dSbhqocO_w**" 
   capabilities="urn:oracle:webcenter:delete"/>
</links>

The invitee can also delete an invitation from his or her own account. The invitee can get a list of his or her invitations by specifying:

GET http://<host:port>/rest/api/people/invitations?q=invitee:equals:@me&utoken=ASDF

Note that the response from a DELETE is simply a status code of 204.

C.15 Content Management REST API

This section supplements the OASIS CMIS specification, and provides details on the specific implementation of the .

The OASIS CMIS (Content Management Interoperability Services) Technical Committee works to standardize a Web services interface specification that will enable greater interoperability of Enterprise Content Management (ECM) systems. For more information, see the OASIS CMIS site:

http://www.oasis-open.org/committees/cmis/

Before continuing, all users should review the OASIS CMIS specification. This section references the Content Management Interoperability Services (CMIS) Version 1.0, which can be viewed at the following URL:

http://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html.

The provides a server that uses the CMIS RESTful AtomPub server binding to provide access to Oracle Content Server repositories configured in your application.

The specification includes the domain model and two server bindings. As mentioned above, only the RESTful AtomPub binding is currently implemented by the . Users should be familiar with Atom and AtomPub, which are the default formats for responses.

Note:

CMIS provides a lowest common denominator for a wide range of different content systems; it is not aligned directly with Oracle WebCenter Content functionality. Refer to the service document to identify available functionality.

This section includes the following topics:

C.15.1 CMIS Domain Model

Section 2: Domain Model in the CMIS specification defines a domain model that can be used by applications to work with one or more Content Management repositories.

C.15.1.1 Data Model

The service document consists of AtomPub workspaces. Each workspace maps to a content connection (only Oracle WebCenter Content repositories are supported by the ). For details on the service document, see the next section, CMIS Part II: RESTful AtomPub Binding.

C.15.1.1.1 Repository

For this release, some of the optional capabilities listed in section 2.1.1 have not been implemented. Versioning, ACL, Policies, Relationships, Change Log, Folder Descendants/Tree, and Renditions will be considered for future releases.

Specifically, the implementation has the following optional capabilities:

capabilityGetDescendants = true
capabilityGetFolderTree = false 
capabilityContentStreamUpdatability = anytime 
capabilityChanges = none
capabilityRenditions = none 
capabilityMultifiling = false 
capabilityUnfiling = false 
capabilityVersionSpecificFiling = false 
capabilityPWCUpdateable = false 
capabilityPWCSearchable = false 
capabilityAllVersionsSearchable = false 
capabilityJoin = none   
capabilityACL = none
capabilityQuery = none, metadataonly, or both combined

C.15.1.1.2 Object

The supports document and folder objects. In CMIS the cmis:baseTypeId for a Node will be cmis:folder or cmis:document. Also, the cmis:baseId for a Type will be cmis:folder or cmis:document.

C.15.1.1.3 Object-Type

A CMIS Object-Type contains fields mapped from the Oracle WebCenter Content: Content Server metadata field definitions and Oracle WebCenter Content's Site Studio region definitions.

The mapping from Oracle WebCenter Content metadata fields to CMIS property definitions is as follows:

Table C-33 Content Server Metadata Mappings

Oracle WebCenter Content Metadata	CMIS Property Definition
TEXT metadata field with option list configured with select list validated and YesNoView or TrueFalseView view	cmis:propertyBoolean
All other TEXT metadata fields	cmis:propertyString
LONG TEXT metadata field	cmis:propertyString
MEMO metadata field	cmis:propertyString
INTEGER metadata field	cmis:propertyInteger
DATE metadata field	cmis:propertyDateTime
DECIMAL metadata field	cmis:propertyDecimal

The mapping from Site Studio region definition fields to CMIS property definitions is as follows:

Table C-34 Site Studio Region Definition Mappings

Site Studio Region Definition	CMIS Property Definition
Image Element Definition fields	cmis:propertyString
WYSIWYG Element Definition fields	cmis:propertyString
Plain Text Element Definition fields	cmis:propertyString
Static List Element Definition fields	cmis:propertyString

C.15.1.1.4 Document Object

Document Objects are the elementary information entities managed by the repository. As defined by the CMIS specification, Document Objects may be version-able, file-able, query-able, control-able and ACLControl-able. As stated earlier, the does not support versioning, multi-filing, Policies or ACL for this release.

If a Node is determined to be a Document (not a Folder) then any children it has will not be exposed through CMIS. In CMIS, each Document Object is associated with a single content stream, and for WebCenter CMIS REST, this stream is the Oracle WebCenter Content: Content Server binary associated with the document.

C.15.1.1.5 Folder Object

The CMIS specification states that Folder Objects do not have a content-stream and are not version-able. If a Node is determined to be a Folder, then the exposes it in this manner. (In Oracle WebCenter Content, folders do not have a content stream and are not versionable).

C.15.1.1.6 Relationship Object

Section 2.1.6: Relationship Object in the CMIS specification is not applicable; the does not support Relationships for this release.

C.15.1.1.7 Policy Object

Section 2.1.7: Policy Object in the CMIS specification is not applicable; the does not support Policies for this release.

C.15.1.1.8 Access Control

Most of Section 2.1.8: Access Control in the CMIS specification is not applicable; the does not support ACL for this release. See the next section for details on allowable actions.

C.15.1.1.8.1 AllowableActions Mapping

This section lists allowable actions defined for Objects. Because of how this release is implemented, some of these are hard-coded for all objects. Other allowable actions will be set based on the repository configuration.

canGetObjectRelationships = false
canCreateRelationship = false
canGetDescendants = false
canGetFolderTree = false
canCheckOut = false (versioning)
canCancelCheckOut = false (versioning)
canCheckIn = false (versioning)
canAddObjectToFolder = false (multi-filing)
canRemoveObjectFromFolder = false (unfiling/multi-filing)
canApplyPolicy = false
canGetAppliedPolicies = false
canRemovePolicy = false
canCreatePolicy = false
canApplyACL = false
canGetACL = false
canGetRenditions = false
canDeleteTree = true
canGetAllVersions = false (versioning)

C.15.1.1.9 Versioning

Section 2.1.9: Versioning in the CMIS specification is not applicable; the does not support versioning for this release.

C.15.1.1.10 Query

CMIS queries return a Result Set where each Entry object will contain only the properties that were specified in the query. The does not support JOINs in queries, so each result entry will represent properties from a single node. Common searches use a query like "SELECT * FROM …".

The FROM clause specifies a content-type to be searched.
- FROM cmis:document ==> any Oracle WebCenter Content document (for example, IDC:GlobalProfile)
- FROM cmis:folder ==> any Oracle WebCenter Content folder (for example, IDC:Folder)
- FROM typeQueryName ==> type's cmis queryName, as long as the type is queryable (for example, ora:t:IDC!;GlobalProfile)
The cmis:document and cmis:folder types are always queryable. Other types will be queryable if they are searchable in the repository.
The IN_FOLDER predicate is implemented as the folder ID specified, being the parent of the results.
The IN_TREE predicate is implemented as the folder ID specified, being a parent in the folder structure of the results.
The CONTAINS() predicate is a full-text query expression operator.
Properties of cmis:document and cmis:folder will be queryable and orderable if their corresponding Oracle WebCenter Content system property is searchable and sortable. The system property mappings are:
- cmis:createdBy ==> dDocAuthor
- cmis:lastModifiedBy ==> dDocCreator
- cmis:creationDate ==> dCreateDate
- cmis:lastModificationDate ==> dLastModifiedDate (for 10g, folders map to dLastModifiedDate and documents map to dCreateDate)
- cmis:name ==> dOriginalName (for a document) or dCollectionName (for a folder)
- cmis:contentStreamFileName ==> dOriginalName
- cmis:contentStreamLength ==> VaultFileSize
- cmis:contentStreamMimeType ==> dFormat
- cmis:objectId ==> dDocName
- cmis:objectTypeId ==> Oracle WebCenter Content profile name or SiteStudio Region Definition name
  
  Note:
  
  cmis:objectTypeId is never orderable.
- cmis:path ==> use IN_FOLDER or IN_TREE predicate
Note:

Some repositories may have capabilities that are not representable in a CMIS query, and some repositories may have restrictions which will limit the CMIS-query predicates (or combinations of predicates) that can be used in a query. Use the mappings above to translate repository capabilities and restrictions into corresponding considerations for CMIS queries.
Nested properties are not queryable or orderable.
The implementation reports as orderable any properties which Oracle WebCenter Content specifies as sortable. This list can include properties which Oracle WebCenter Content cannot actually sort on. To allow ordering on a field for which Oracle WebCenter Content reports a sort error, follow the steps below to make the specified Oracle WebCenter Content field sortable:
1. Go to Administration and open Admin Applets.
2. Open the Configuration Manager applet and click Advanced Search Design.
3. Edit the field you wish to make orderable and select Is sortable.
4. Save your changes and exit Administration.

Table C-35 lists specific search considerations and recommendations. For example queries, see Best Practices and Examples.

Table C-35 Search Considerations and Recommendations

Consideration	Recommendation
Oracle WebCenter Content provides limited support for querying on null or non-null values.	Be aware of the differences in search behavior and do not write search expressions that depend on unsupported criteria.
Recursive search for folders is not supported by Oracle WebCenter Content, but is supported for documents if configured on the Oracle WebCenter Content server as described to the right.	Scope the search to only include documents (add a select clause like `select * from cmis:document`). Set the search path on the Search object (add a where clause like "`where IN_TREE('/StellentRepository/IDC:Folder/2`'). Configure the `folders_g CollectiveSearchRecursiveContent` and related settings like `CollectionMaxBranch` in the Oracle WebCenter Content config.cfg file.
Multivalued property operators perform substring matches. This is true for `ANY <multiValuedQueryName> IN (<literal>, ...)` or `<literal> = ANY < multiValuedQueryName>`. In Oracle WebCenter Content, a field with an option list stores values in a comma-delimited manner. For example, if you have values "A", "B", and "C", these will be represented as "A, B, C". Using an ANY or ANY IN search for 'A, B' will find this item.	Be aware of the differences in search behavior and consider changing the Oracle WebCenter Content option list delimiter character in the Configuration Manager applet to reduce the potential for finding extra matches.
When searching folders (`FROM cmis:folder`), at most one value can be specified per criteria. Each criteria is logically ANDed with the others to make a more selective query. There is no support for `OR` or `NOT` operators when searching folders.	Do not use `OR` and `NOT` in Oracle WebCenter Content folder search.
Not all properties are searchable, and if the search encounters a property that is not searchable, it will return a ParseException (400 error).	Understand which properties are searchable for a given content type by examining the Oracle WebCenter Content Configuration Manager information fields section, or by reviewing the ContentType definition. Examine the URL for the `isSearchable` field setting Example URLS: `http://myContentServer/idc/idcplg?IdcService=VCR_GET_CONTENT_TYPE&vcrContentType=IDC:Folder&IsSoap=1` Or, examine the specific type through CMIS.
Not all ContentTypes are searchable. An attempt to search for a non-searchable ContentTypes will throw an exception. For example, the `IDC:FileReference` ContentType is not searchable.	Be aware that not all ContentTypes are searchable.
Only String multi-valued properties can be searched.	Do not specify search for multi-valued property types other than String.
The `NOT` operator cannot be used for `LONG` properties.	Try to restructure the query using supported syntax.
Only one sort criteria is supported.	Do not write search expressions that use more than a single sort criteria.
Sorting on non-indexed fields results in an exception. Searching on a non-indexed field throws an exception, with the embedded exception code of, for example, "DRG-10837: section dStatus does not exist".	Understand which fields have been indexed before using them as sort criteria. Examine the URL for the `isSortable` field definition. Example URL: `http://myContentServer/idc/idcplg?IdcService=GET_ADVANCED_SEARCH_OPTIONS&IsSoap=1`, Or examine the type through CMIS to see if the property definition is queryable.
Empty values are not allowed in a search query.	Do not use a criteria such as `cmis:name != ''.`.
The `Notequals` operator is not supported for non-String properties	Be aware of the differences in search behavior and do not write search expressions that depend on unsupported criteria.
Multiple search paths on the same Oracle WebCenter Content repository are not supported.	Be aware of the differences in search behavior and do not write search expressions that depend on unsupported criteria.
When searching for documents, recursive search (folder tree search) is supported if Oracle WebCenter Content is configured properly. If the search path is not set, then all documents in the repository will be searched (both filed and unfiled).	Configure the content server `folders_g CollectionSearchRecursiveContent` and related settings like `CollectionMaxBranch` in the Oracle WebCenter Content config.cfg file. These settings are described in the Oracle WebCenter Content documentation. To perform a document search scoped to a folder tree, use the IN_TREE predicate.
When searching for documents and using the `LIKE` operator, wildcards (`%`) are only supported in the last path element.	Be aware of the differences in search behavior and do not write search expressions that depend upon unsupported criteria.
When searching documents (select * from cmis:document), it is not possible to limit the search to more than just a single content type; for example, this is not supported: `select * from IDC:MyProfile, IDC:AnotherProfile` because it has multiple explicit content types and `JOINS` are not supported.	If you need to limit the search to more than just a single content type, issue multiple queries to achieve the same behavior. If you want to search across all types, use cmis:document in the select statement.
Oracle WebCenter Content search does not support `OR` when `cmis:objectTypeId` is specified in a query; other parameters can be ANDed with this criteria, but `OR` is not supported.	If this functionality is necessary, issue multiple queries to achieve the same behavior.
The `cmis:objectTypeId` criteria only supports `==`, `!=`, and `like`. Use of `!=` is restricted to the case of excluding folders (which behaves the same as adding `select * from cmis:document`).	Be aware of the valid operators when using `cmis:objectTypeId` criteria.
Queries may be case-sensitive depending on the selected Oracle WebCenter Content search engine.	Be aware that the Oracle WebCenter Content search engine selection can affect case-sensitivity. Metadata searches using OracleTextSearch as the search engine are generally case-insensitive. Metadata searches using `DATABASE.FULLTEXT` as the search engine are generally case-sensitive. The exact behavior sometimes varies by metadata field.

C.15.1.2 Services

The methods described in Section 2.2 Services of the CMIS specification are implemented by the ; specific implementation details are covered in CMIS Part II: RESTful AtomPub Binding.

C.15.2 CMIS Part II: RESTful AtomPub Binding

Section 3: RESTful AtomPub Binding in the CMIS specification defines a specification based on AtomPub that can be used by applications to work with one or more Content Management Repositories. REST services are available through a portal instance.

C.15.2.1 Service Document

All navigation of a repository begins with the AtomPub Service Document. From this document, all accessible content in a repository can be discovered through the collections, links, and templates. The URI to the service document, relative to the CMIS web application's context-root, is /rest/cmis/repository.

Therefore, if an application is deployed with a library-context-root-override as in the example above, the service document would be accessed through the following URL: http://hostname:port/rest/cmis/repository

By default, this document will contain a workspace for each configured Oracle WebCenter Content repository (only Oracle WebCenter Content repositories are supported by CMIS REST in Oracle WebCenter Portal). A service document for a single repository can be obtained by using the repositoryId query parameter, as described in section 3.6.2.1 of the CMIS AtomPub binding specification.

As noted in the previous section, the service document consists of AtomPub workspaces. Each workspace maps to a Oracle WebCenter Portal Content Server connection.

Specific URIs beyond the service document are not published; it is assumed that users will start at the service document and navigate the collections and links down expected paths. The relationships of the links and the titles and types of the collections are all defined in the CMIS specification, and thus can be commonly navigated by a client implementation. There are also templates defined for each repository, for easier access of objects by path, object by ID, type by ID, and queries. The format of the variables for the path and ID templates can be discovered by viewing the Entries of Folders and Documents.

C.15.2.2 Response Formats

Section 3.1.3: Response Formats in the CMIS specification indicates that Atom/AtomPub style formats will be returned by default unless overridden by a supported media type expressed in the Accept header.

A generic AtomPub feed reader can walk through any of the feeds returned by the CMIS REST server. It will not see all the CMIS specifics, but will be able to navigate through links. In general, to set up a feed reader, you need to know the URI of a particular feed, which can be discovered by navigating through the service document, for example, the workspace link for "typesdescendants".

For details on query syntax, see the CMIS specification. For best practices and examples, see Best Practices and Examples.

C.15.2.3 Additional Functionality

The provides the following additional functionality beyond the CMIS specification.

C.15.2.3.1 Folder Children Collection

The specification defines the following CMIS services:

GET: getChildren
POST: createDocument or createFolder or createPolicy or moveObject or addObjectToFolder

The provides the following additional services:

POST: create This service has five query parameters: uid, fileName, contentId, comments, simpleResponse, and one header parameter: Slug. This service is meant to be used as a simple binary request upload. A new document is created with this service. Slug and fileName are used to name the binary that is attached to the request (using both parameters is optional; only one needs to be defined and fileName is checked first). The comments parameter is optional and contentId is optional if Oracle WebCenter Content is set up to auto-generate the dDocName.
POST: create Content-Type: multipart/form-data This service has a single query parameter: uid, which is the uid of the folder in which the document is to be created. The boolean query parameter simpleResponse will return a response of media type: application/atom+xml;type=entry, if set to false. If set to true, a response of media type: text/html will be returned with a URI pointing to the newly created document. The comments and simpleResponse parameters are both optional, contentId is optional if Oracle WebCenter Content is set up to auto-generate the dDocName, and the name "fileUpload" is required.
```
<html>
<head>
    <title>simple post</title>
</head>
<body>
<form action="http://<host>:<port>/rest/api/cmis/children/StellentRepository?uid=IDC:Folder/2"
      method="POST"
      enctype="multipart/form-data">
    Select a document to upload: <input type="file" name="fileUpload"/><br>
     <input type="hidden" name="comments" value="this is just a comment"/>
     <input type="hidden" name="contentId" value="uniqueID1"/>
     <input type="hidden" name="simpleResponse" value="true"/> 
    <input type="submit" value="Submit"/>
</form>
</body>
</html>
```

C.15.2.3.2 Document Entry

The specification defines the following CMIS services:

GET: getObject, getObjectOfLatestVersion (getObject)
PUT: updateProperties
DELETE: deleteObject

The provides the following additional services:

POST: postToDelete This service has two query parameters: uid and _method, and allows a document to be deleted through POST.
```
http://<host>:<port>/rest/api/cmis/document/repoName?uid=ABC&_method="delete"
```

C.15.2.3.3 Content Stream

The specification defines the following CMIS services:

GET: getContentStream
PUT: setContentStream
DELETE: deleteContentStream

The provides the following additional services:

POST: postTunnelContentStream This service has five query parameters: uid, overwriteFlag, fileName, comments, _method, and one header parameter: Slug. This service is meant to be used as a simple binary request upload or delete through POST. A document must already exist for this service. Slug and fileName are used to name the binary that is attached to the request (using both parameters is optional; only one needs to be defined and fileName is checked first). The overwriteFlag parameter defaults to true, the comments parameter is optional and valid values for _method are "delete" or "put" (not case sensitive).
```
http://<host>:<port>/rest/api/cmis/stream/repoName?uid=ABC&_method="delete"
```

POST: postTunnelContentStream Content-Type: multipart/form-data This service has a single query parameter: uid and is meant to be used as a simple html multipart/form-data upload or delete through POST. A document must already exist for this service. The attribute name="fileUpload" is required, "comments" is optional, and valid values for "_method" are "delete" or "put" (not case sensitive).

<form action="http://<host>:<port>/rest/api/cmis/stream/repoName?uid=WDOC019113"
      method="POST"
      enctype="multipart/form-data">
    Select a document to upload: <input type="file" name="fileUpload"/><br>
     <input type="hidden" name="comments" value="this is just a comment"/>
     <input type="hidden" name="_method" value="PUT"/>
    <input type="submit" value="Submit"/>
</form>

C.15.3 Best Practices and Examples

This section provides best practices and examples using the . For details on query syntax, see the CMIS specification.

This section includes the following topics:

C.15.3.1 Best Practices

The following list provides suggested best practices for repositories that use the .

To determine the types that can be used in the "FROM" portion of a query, see the types collection from the AtomPub service document. The type must be queryable and the query name of that type must be used.

For example, IDC:GlobalProfile might have type information similar to the following:
```
<cmis:localName>IDC:GlobalProfile</cmis:localName>            
<cmis:displayName>IDC:GlobalProfile</cmis:displayName>            
<cmis:queryName>ora:t:IDC!;GlobalProfile</cmis:queryName>            
<cmis:queryable>true</cmis:queryable>
```
An example query for the type information above could be: "SELECT * FROM ora:t:IDC!;GlobalProfile".

To determine the properties that can be used in the "SELECT" and "WHERE" portions of a query, see the entry for the associated type. Each property definition of that type will be listed and will have a setting for queryable and orderable. The cmis:queryname will be the value to be used in the query.

For example, IDC:GlobalProfile might have property definition information similar to the following:

<cmis:propertyStringDefinition>
              <cmis:id>/stanl18-ucm11g/IDC:GlobalProfile.ora:p:dDocName</cmis:id>
              <cmis:localName>dDocName</cmis:localName>
              <cmis:displayName>dDocName</cmis:displayName>
              <cmis:queryName>ora:p:dDocName</cmis:queryName>
              <cmis:description>Content ID</cmis:description>
              <cmis:propertyType>string</cmis:propertyType>
              <cmis:cardinality>single</cmis:cardinality>
              <cmis:updatability>readwrite</cmis:updatability>
              <cmis:inherited>false</cmis:inherited>
              <cmis:required>false</cmis:required>
              <cmis:queryable>true</cmis:queryable>
              <cmis:orderable>true</cmis:orderable>
            </cmis:propertyStringDefinition>

An example query for the property definition information above could be: "SELECT ora:p:dDocName FROM ora:t:IDC!;GlobalProfile"

To keep queries more readable, avoid non-alphanumeric characters in ContentType and PropertyDefinition names.

C.15.3.2 Examples

This section provides some example queries. For details on query syntax, see the CMIS specification. (To get the full URI for a query, see the query URI template in the service document.)

SELECT * from cmis:folder
SELECT cmis:name, cmis:contentStreamFileName, cmis:contentStreamMimeType, cmis:contentStreamLength FROM cmis:document WHERE cmis:contentStreamFileName = 'BinaryName' AND cmis:contentStreamMimeType = 'text/html' AND cmis:contentStreamLength > 1
SELECT cmis:name, cmis:creationDate, cmis:lastModificationDate FROM cmis:folder WHERE cmis:name = 'Trash' AND cmis:lastModificationDate > TIMESTAMP '2008-05-18T10:32:44.703-06:00'
SELECT * FROM cmis:document WHERE cmis:name LIKE 'baker%'
SELECT * FROM cmis:document WHERE cmis:name NOT IN ('nodeBoolean', 'nodeLong')
SELECT cmis:name from cmis:document where IN_TREE('/StellentRepository')
SELECT * FROM ora:t:IDC:GlobalProfile WHERE ora:p:xBooleanTestField = FALSE ORDER BY ora:p:dDocTitle ASC
SELECT ora:p:xMultiValuedDelimiterTest FROM ora:t:IDC:GlobalProfile WHERE ANY ora:p:xMultiValuedDelimiterTest NOT IN ('four')
SELECT cmis:name FROM ora:t:IDC:GlobalProfile WHERE CONTAINS('test') ORDER BY ora:p:dInDate DESC
SELECT * FROM cmis:document where IN_TREE('/StellentRepository/IDC:Folder/2')

C.16 Using the Events REST API

WebCenter Portal provides a REST API to support events. Use the REST API to create your own interface for providing access to portal events.

Note:

The Events REST API is available for portal events only. You cannot use the REST API to work with personal events.

This section describes the REST API methods associated with events. It includes the following topics:

C.16.1 Events Entry Point

The entry point for events can be reached only through a portal. First you need to navigate to the appropriate portal and then find the link element with a resourceType of:

urn:oracle:webcenter:events:gsEvents

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with events.

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.16.2 Events Resource Type Taxonomy

When the client has identified the entry point, it can then navigate through the resource type taxonomy to perform the required operations. For more information about the individual resources types, see the appropriate section in Events Resource Types.

The taxonomy for events is:

urn:oracle:webcenter:events:gsEvents
  urn:oracle:webcenter:events:gsEvent
urn:oracle:webcenter:events:gsCategories

C.16.3 Security Considerations

There are no specific security considerations for events. For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.16.4 Events Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.16.4.1 urn:oracle:webcenter:events:gsEvents

Use this resource to identify the URI to use to retrieve (GET) and create (POST) portal events. The response from a GET operation includes each portal event in this collection of events, and each event includes links used to operate on that event. The response from a POST operation includes the event that was created in this collection of events and a link to operate on that event.

C.16.4.1.1 Navigation Paths to gsEvents

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   spaces
      gsEvents

C.16.4.1.2 Supported Methods for gsEvents

The following methods are supported by this resource:

GET
- request - body: <gsCategory>, Parameters: startIndex, itemsPerPage, utoken
  
  For information about these common parameters, see Common Request Query Parameters.
  
  The following additional parameters are available:
  - startDate—the date from which to start listing portal events
  - endDate—the date at which to stop listing portal events
  For the start and end dates, use the format YYYY-MM-DD, for example 2011-09-01. You can also specify a time (for example, 2011-09-01T09:00:00) and a timezone sign (for example, for UTC, 2011-09-01T09:00:00Z).
- response - body: 0 or more events
POST
- request - body: event
- response - body: event

C.16.4.1.3 Resource Types Linked to From gsEvents

Table C-36 lists the resource types that the client can link to from this resource.

Table C-36 Related Resource Types for gsEvents

rel	resourceType
self	urn:oracle:webcenter:events:gsEvents

C.16.4.2 urn:oracle:webcenter:events:gsEvent

Use this resource type to identify the URI to use to read (GET), update (PUT), or delete (DELETE) a specific portal event. The response from a GET operation includes the specific event identified by the URI. The response from a PUT operation includes the modified version of the event identified by the URI. The response from a DELETE operation is a 204.

C.16.4.2.1 Navigation Paths to gsEvent

resourceIndex
   spaces
      gsEvents
         gsEvent

C.16.4.2.2 Supported Methods for gsEvent

The following methods are supported by this resource:

GET
- request - body: none
- response - body: event
PUT
- request - body: event
- response - body: event
DELETE
- request - body: none
- response - body: none

C.16.4.2.3 Writable Elements for gsEvent

Table C-37 lists the writable elements for this resource.

Table C-37 Writable Elements for gsEvent

Element	Type	Required	Constraints	Description
`category`	String	No	The name of an event category defined for the portal	The category to which the event belongs. Note: If the category does not exist, the default is used if the event is being created. However, an error will occur if the event is being modified.
`details`	String	No	1 or more characters	Additional details about the event
`endTime`	Date	Yes	YYYY-MM-DDTHH:MM:SS `endTime` must be greater than or equal to `startTime`	The date and time at which the event ends
`location`	String	No	1 or more characters	The location at which the event takes place
`priority`	String?	No	1 - Highest 2 - High 3 - Normal 4 - Low 5 - Lowest	The priority of the event, which determines where it appears when events clash
`startTime`	Date	Yes	YYYY-MM-DDTHH:MM:SS	The date and time at which the event starts
`summary`	String	Yes	1 or more characters	A brief description of the event to serve as the title of the event

C.16.4.2.4 Read-only Elements for gsEvent

Table C-38 lists the read-only elements for this resource.

Table C-38 Read-only Elements for gsEvent

Element	Type	Description
`author`	personReference	User who created the event
`created`	Date	Date on which the event was created
`duration`	String	The length (in minutes) of the event
`groupSpace`	groupSpaceReference	The portal to which the event belongs
`id`	String	Unique ID of the event
`isAllDayEvent`	Boolean	Indicates whether the event takes place over an entire day
`modified`	Date	Date on which the event was last updated
`modifiedByUser`	personReference	User who last updated the event

C.16.4.2.5 Resource Types Linked to from gsEvent

Table C-39 lists the resource types that the client can link to from this resource.

Table C-39 Related Resource Types for gsEvent

rel	resourceType
self	urn:oracle:webcenter:events:gsEvent

C.16.4.3 urn:oracle:webcenter:events:gsCategories

Use this resource to identify the URI to use to retrieve (GET) and create (POST) portal event categories. The response from a GET operation includes each category in this collection of categories, and each category includes links used to operate on that category. The response from a POST operation includes the category that was created in this collection of categories and a link to operate on that category.

C.16.4.3.1 Navigation Paths to gsCategories

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   spaces
      gsCategories

C.16.4.3.2 Supported Methods for gsCategories

The following methods are supported by this resource:

GET
- request - body: category
- response - body: 0 or more categories
POST
- request - body: category
- response - body: category

C.16.4.3.3 Resource Types Linked to From gsCategories

Table C-40 lists the resource types that the client can link to from this resource.

Table C-40 Related Resource Types for gsCategories

rel	resourceType
self	urn:oracle:webcenter:events:gsCategories

C.17 Using the Tags REST APIs

WebCenter Portal provides REST APIs to support tags. Use the tags REST APIs to do the following:

Find all tags or find a subset of tags by criteria
Get a specific tag
Delete tags
Update or rename tags
Get tagged items
Untag an item
Add a new tagged item
Change tags for a tagged item
Find all tagged items or find tagged items by a filter, such as a date or a tag word
Get related users by tag

This section describes the REST APIs associated with tags. It includes the following topics:

For an introduction to the REST APIs, see Introduction to the WebCenter Portal REST APIs.

C.17.1 Tags Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. To find the entry point for tags, find the link element with a resourceType of one of the following:

urn:oracle:webcenter:tagging:tags
urn:oracle:webcenter:tagging:taggeditems
urn:oracle:webcenter:tagging:users

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with tags.

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.17.2 Tags Resource Type Taxonomy

When the client has identified the entry point, it then can navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Resource Type.

The taxonomy for tags is:

urn:oracle:webcenter:tagging:tags
   urn:oracle:webcenter:tagging:tag
urn:oracle:webcenter:tagging:taggedItems
   urn:oracle:webcenter:tagging:taggedItem
urn:oracle:webcenter:tagging:users

Under users, you can add the resource type for that object, such as peopleprofile.

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

Collection resources in the tags resources support pagination (itemsPerPage and startIndex for tags and users and itemsPerPage for taggedItems). Other query parameters (search and projection) are not supported.

C.17.3 Security Considerations

Authentication is required before using REST API methods.

For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.17.4 Tags Resource Types

This section provides information about each resource type. It includes the following topics:

C.17.4.1 urn:oracle:webcenter:tagging:tags

Use this resource type to identify the URI to use to read (GET) tags. The response from a GET operation includes all tags, a specific tag, a subset of tags, or a tag related to a specific list of tags or users.

C.17.4.1.1 Navigation Paths to tags

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   tags

resourceindex
   spaces
      spaces:resourceindex
         spaces:tags

C.17.4.1.2 Supported Methods for tags

The following methods are supported by this resource:

GET
- request - body: none, Parameters: startIndex, itemsPerPage, keyword, serviceId, relatedTag, userId, scopeGuid, shared, tags, users
- response - body: tag
where:
- startIndex—Specifies the index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.
- itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.
- keyword—Specifies a keyword for substring matches.
- serviceId—Specifies the service ID for which you want to find tags (null for all).
- relatedTag—Specifies a tag that is related to the list of tags. For example, if you have tagged item1 as "webcenter help" and item2 as "webcenter document" and you set relatedTag=webcenter, then you would get both tags (for help and document) returned.
- userId—Specifies a single user ID to find tags for (null for all). Uses logged-in user if null and not looking for shared tags.
- scopeGuid—Specifies the GUID of the portal. When set to the Home portal, it shows all (unfiltered) tags.
- shared—Specify true to return personal resources only (that is, resources tagged privately only by that same user); false to return system resources (that is, resources with at least one public tag).
- tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.
- users—Specifies to filter by this list of users separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.

Note:

Parameters can be used in certain combinations only.

Table C-41 shows the available parameter combinations for each operation. For example, the tags parameter cannot be specified with the serviceId parameter.

Table C-41 Parameter Combinations Available for Getting Tags

API Method	keyword	serviceId	relatedTag	userId	scopeGuid	shared	tags	users
findRelatedSystemTags	-	-	X	-	X	-	X	X
findPopularTagsCommon	X	X	-	X	-	X	-	-
findPopularTags (with GUID)	X	-	-	X	X	X	-	-
findPopularTags	X	-	-	X	-	X	-	-

C.17.4.1.3 Resource Types Linked to From tags

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

Table C-42 lists the resource types that the client can link to from this resource. Tags have a reference link to themselves and to the next page or previous page of results.

Table C-42 Related Resource Types for tags

rel	resourceType
self	urn:oracle:webcenter:tagging:tags
Previous/Next	urn:oracle:webcenter:tagging:tags

C.17.4.2 urn:oracle:webcenter:tagging:tag

Use this resource type to identify the URI to use to read (GET), rename (PUT), and delete (DELETE) a tag. The response from a GET operation includes all tags, a specific tag, a subset of tags, or a tag related to a specific list of tags or users.

C.17.4.2.1 Navigation Paths to tag

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   tags
      tag

resourceindex
   spaces
      spaces:resourceindex
         spaces:tags
            spaces:tag

C.17.4.2.2 Supported Methods for tag

The following methods are supported by this resource:

GET
- request - body: none, Parameters: none
- response - body: tag
PUT
- request - body: tag
- response - body: tag
DELETE
- request - body: none
- response - body: none

Example: Body of the PUT command for Renaming a Tag

<tag>
<name>newId</name>
</tag>

C.17.4.2.3 Resource Types Linked to From tag

Table C-43 lists the resource types that the client can link to from this resource. A tag has a reference link to itself, to related taggedItems, to related users, and to related tags.

Table C-43 Related Resource Types for tag

rel	resourceType
self	urn:oracle:webcenter:tagging:tag urn:oracle:webcenter:tagging:taggedItems urn:oracle:webcenter:tagging:users urn:oracle:webcenter:tagging:tags

C.17.4.3 urn:oracle:webcenter:tagging:taggedItems

Use this resource type to identify the URI to use to read tagged items and their related resources (GET) or to add tagged items (POST).

The response from a GET operation includes a tagged item or all tagged items, which can be filtered by date, tag words, and so on. Each tag includes links used to operate on that tag. The response from a POST operation includes the tagged items that were created in this collection of tags and a link to operate on them.

C.17.4.3.1 Navigation Paths to taggedItems

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   taggedItems

resourceindex
   spaces
      spaces:resourceindex
         spaces:taggedItems

C.17.4.3.2 Supported Methods for taggedtems

The following methods are supported by this resource:

POST

request - body: taggedItem
response - body: taggedItem

<taggeditem>
   <serviceId>oracle.webcenter.page</serviceId>
  
<resourceId>/oracle/webcenter/page/somepath/someotherpath/a.jspx</resourceId>
   <tagWords>foo bar boo far</tagWords>
   <resourceTitle>This is renamed by me to be foofoo</resourceTitle>
   <scopeGuid>(optional) scope for the item</scopeGuid>
   <shared>(optional) make the item private </shared>
 </taggeditem>

GET
- request - body: none, Parameters: serviceId, keyword, relatedRID, tags, users, dt, scopeGuid, shared, itemsPerPage
- response - body: tagged items
where:
- serviceId—Specifies the service ID of the item.
- keyword—Specifies a keyword in the resource title.
- relatedRID—Specifies a related tag. For example, if you tagged item1 as "webcenter help" and item2 as "fusionapps documents" and item3 as "webcenter documents" and set relatedRID=item3, then you would get back item1 and item2, because they share tags in common with item3.
- tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.
- users—Specifies to filter by these users, separated by URL-encoded spaces ('+'); for example, {USER}+{USER}+...+{USER}.
- dt—Specifies to filter bookmarks by this date, which defaults to the most recent date on which bookmarks were saved {DD-MM-CCYY}.
- scopeGuid—Specifies the GUID of the portal. When set to the Home portal, it shows all (unfiltered) tags.
- shared—Specify true to return personal resources only (that is, resources tagged privately only by that same user); false to return system resources (that is, resources with at least one public tag).
- itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.

Note:

Parameters can be used in certain combinations only.

Table C-44 shows the available parameter combinations for each operation. For example, the tags parameter cannot be specified with the serviceId parameter.

Table C-44 Parameter Combinations Available for Getting Tagged Items

API Method	serviceId	keyword	relatedRID	tags	users	dt	scopeGuid	shared
findRelatedSystemResources	X	-	X	-	-	-	-	-
findUpdatedResources	-	-	-	-	-	X	X	-
findSystemResources		-	-	X	X	-	X	X
findFilterPersonalResources	X	X	-	-	-	-	X	-
findPersonalResources	-	-	-	X	X	-	X	X
findFilteredPersonalResources (no keyword)	X	-	-	-	-	-	X	-

C.17.4.3.3 Resource Types Linked to From taggedItems

Table C-45 lists the resource types that the client can link to from this resource. Tagged items have a reference link to themselves and to the next page or previous page of results.

Table C-45 Related Resource Types for taggedItems

rel	resourceType
self	urn:oracle:webcenter:tagging:taggedItems
Previous/Next	urn:oracle:webcenter:tagging:taggedItems

C.17.4.4 urn:oracle:webcenter:tagging:taggedItem

Use this resource type to identify the URI to use to read tagged items and their related resources (GET), add tagged items (POST), update tags for a tagged item (PUT), and remove all tags from an item (DELETE).

The response from a GET operation includes a tagged item or all tagged items, which can be filtered by date, tag words, and so on. Each tag includes links used to operate on that tag. The response from a POST operation includes the tagged item that was created in this collection of tags and a link to operate on that tagged item.

Navigation Paths to taggedItem

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   taggedItems
      taggedItem
 
resourceindex
   spaces
      spaces:resourceindex
         spaces:taggedItems
            spaces:taggedItem

C.17.4.4.1 Supported Methods for taggedItem

The following methods are supported by this resource:

GET
- request - body: none, Parameters: serviceId, keyword, tags, users, dt, shared, itemsPerPage
- response - body: tagged item
where:
- serviceId—Specifies the service ID of the item.
- keyword—Specifies a keyword in the resource title.
- tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.
- users—Specifies to filter by this list of users separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.
- dt—Specifies to filter bookmarks by this date, which defaults to the most recent date on which bookmarks were saved {DD-MM-CCYY}.
- shared—Specify true to return personal resources only (that is, resources tagged privately only by that same user); false to return system resources (that is, resources with at least one public tag).
- itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.

PUT

request - body: taggedItem
response - body: taggedItem

<taggeditem>
<tagWords>foo bar boo far</tagWords>
</taggeditem>

DELETE
- request - body: none
- response - body: none

C.17.4.4.2 Resource Types Linked to From taggedItem

Table C-46 lists the resource types that the client can link to from this resource. A tagged item has a reference link to itself, related tagged items, and an external link.

Table C-46 Related Resource Types for taggedItem

rel	resourceType
self	urn:oracle:webcenter:tagging:taggedItem urn:oracle:webcenter:tagging:taggedItems
alternate	The resource type depends on the type of resource tagged; for example, a page would be urn:oracle:webcenter:page:page

rel

resourceType

self

urn:oracle:webcenter:tagging:taggedItem

urn:oracle:webcenter:tagging:taggedItems

alternate

The resource type depends on the type of resource tagged; for example, a page would be urn:oracle:webcenter:page:page

C.17.4.5 urn:oracle:webcenter:tagging:users

Use this resource type to get a list of people related to a given list of tags.

C.17.4.5.1 Navigation Paths to users

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   taggingusers

resourceindex
   spaces
      spaces:resourceindex
         spaces:taggingusers

C.17.4.5.2 Supported Methods for users

The following methods are supported by this resource:

GET
- request - body: none, Parameters: startIndex, itemsPerPage, tags, users
- response - body: people profile
where:
- startIndex—Specifies the index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.
- itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.
- tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.
- users—Specifies to filter by this list of users separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.

C.17.4.5.3 Resource Types Linked to From users

Table C-47 lists the resource types that individual users can link to from this resource. Users have a reference link to themselves and to the next page or previous page of results.

Table C-47 Related Resource Types for users

rel	resourceType
self	urn:oracle:webcenter:tagging:users
Previous/Next	urn:oracle:webcenter:tagging:users

C.18 Using the Discussions REST API

WebCenter Portal provides a REST API to support discussions. Use the discussions REST API to post, read, update, and delete discussion forums, topics, and messages.

Note:

Beginning with 12c (12.2.1.3.0), Oracle WebCenter Portal has deprecated support for Jive features (announcements and discussions). If you are upgrading from a prior release, these features remain available in your existing installations that are being upgraded.

This section describes the REST API methods associated with discussions. It includes the following topics:

C.18.1 Discussions Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. To find the entry point for discussions, find the link element with a resourceType of:

urn:oracle:webcenter:discussions:forums

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with discussions.

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.18.2 Discussions Resource Type Taxonomy

The taxonomy for discussions is:

urn:oracle:webcenter:discussions:forums
   urn:oracle:webcenter:discussions:forum
   urn:oracle:webcenter:discussions:forum:topics
      urn:oracle:webcenter:discussions:forum:topic
      urn:oracle:webcenter:discussions:forum:topic:messages
         urn:oracle:webcenter:discussions:forum:topic:message

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

Collection resources in the discussions resources support pagination (startIndex and itemsPerPage). Other query parameters are not supported (that is, search and projection).

C.18.3 Security Considerations

There are no specific security considerations for discussions. For general security considerations, see Introduction to the WebCenter Portal REST APIs.

C.18.4 Discussions Resource Types

This section provides the information about each resource type. It includes the following topics:

C.18.4.1 urn:oracle:webcenter:discussions:forums

Use this resource type to identify the URI to use to read (GET) and write (POST) discussion forums. The response from a GET operation includes each forum in this collection of forums, and each forum includes links used to operate on that forum. The response from a POST operation includes the forum that was created in this collection of forums and a link to operate on that forum.

C.18.4.1.1 Navigation Paths to forums

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums

C.18.4.1.2 Supported Methods for forums

The following methods are supported by this resource:

GET
- request - body: none, Parameters: startIndex, itemsPerPage (pagination)
- response - body: forums
POST
- request - body: forum
- response - body: forum

Note that the number of forums displayed per page defaults to 10. For more information, see Templates.

C.18.4.1.3 Resource Types Linked to From forums

Table C-48 lists the resource types that the client can link to from this resource.

Table C-48 Related Resource Types for forums

rel	resourceType
self	`urn:oracle:webcenter:discussions:forums` `urn:oracle:webcenter:discussions:forum`

C.18.4.2 urn:oracle:webcenter:discussions:forum

Use this resource type to identify the URI to use to read (GET), update (PUT), and delete (DELETE) a specific discussion forum. The response from a GET operation includes the specific forum identified by the URI. The response from a PUT operation includes the modified version of the forum identified by the URI. The response from a DELETE operation is a 204.

C.18.4.2.1 Navigation Paths to forum

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      forum

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            forum

resourceindex
   activities
      forum

C.18.4.2.2 Supported Methods for forum

The following methods are supported by this resource:

GET
- request - body: none
- response - body: forum
PUT
- request - body: forum
- response - body: forum
DELETE
- request - body: none
- response - body: none

C.18.4.2.3 Writable Elements for forum

Table C-49 lists the writable elements for this resource.

Table C-49 Writable Elements for forum

Element	Type	Required	Constraints	Description
`name`	String	Yes	1 or more characters	Name of the forum
`displayName`	String	No	1 or more characters	Name used in presentation
`description`	String	No	1 or more characters	Description of the forum

C.18.4.2.4 Read-only Elements for forum

Table C-50 lists the read-only elements for this resource.

Table C-50 Read-only Elements for forum

Element	Type	Description
`id`	Integer	ID of the forum
`parentId`	Integer	ID of the parent category
`createdBy`	String	ID of the user that created the forum
`author`	personReference	User information about the user that created the forum, including GUID, ID, display name, and a link to the profile icon (same user as `createdBy`)
`createdOn`	Date	Date on which the forum was created
`updatedBy`	String	ID of the user that performed the last modification
`modifiedBy`	personReference	User information about the user that performed the last modification, including GUID, ID, display name, and a link to the profile icon (same user as `updatedBy`)
`updatedOn`	Date	Date on which the forum was last modified
`webUrl`	String	URL for direct access to the discussions server
`topicCount`	Integer	Number of topics
`messageCount`	Integer	Number of messages
`locked`	Boolean	True if this forum is locked
`favorite`	Boolean	True if this forum is marked as a favorite

C.18.4.2.5 Resource Types Linked to From forum

Table C-51 lists the resource types that the client can link to from this resource.

Table C-51 Related Resource Types for forum

rel	resourceType
self	`urn:oracle:webcenter:discussions:forum` `urn:oracle:webcenter:discussions:forum:topics`

C.18.4.3 urn:oracle:webcenter:discussions:forum:topics

Use this resource type to identify the URI to use to read (GET) and write (POST) discussion topics. The response from a GET operation includes each topic in this collection of topics, and each topic includes links used to operate on that topic. The response from a POST operation includes the topic that was created in this collection of topics and a link to operate on that topic.

C.18.4.3.1 Navigation Paths to topics

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics

C.18.4.3.2 Supported Methods for topics

The following methods are supported by this resource:

GET
- request - body: none, Parameters: startIndex, itemsPerPage (pagination)
- response - body: topics
POST
- request - body: topic
- response - body: topic

For more information, see Templates.

C.18.4.3.3 Resource Types Linked to From topics

Table C-52 lists the resource types that the client can link to from this resource.

Table C-52 Related Resource Types for topics

rel	resourceType
self	`urn:oracle:webcenter:discussions:forum:topics` `urn:oracle:webcenter:discussions:forum:topic`

C.18.4.4 urn:oracle:webcenter:discussions:forum:topic

Use this resource type to identify the URI to use to read (GET), update (PUT), and delete (DELETE) a specific discussion topic. The response from a GET operation includes the specific topic identified by the URI. The response from a PUT operation includes the modified version of the topic identified by the URI. The response from a DELETE operation is a 204.

C.18.4.4.1 Navigation Paths to topic

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics
         topic

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics
               topic

resourceindex
   activities
      topicT

C.18.4.4.2 Supported Methods for topic

The following methods are supported by this resource type:

GET
- Request—Body: none
- Response—Body: topic
PUT
- Request—Body: topic
- Response—Body: topic
DELETE
- Request—Body: none
- Response—Body: none

C.18.4.4.3 Writable Elements for topic

Table C-53 lists the writable elements for this resource type.

Table C-53 Writable Elements for topic

Element	Type	Required	Constraints	Description
`subject`	String	Yes	1 or more characters	Subject of the topic
`body`	String	No	0 or more characters	Contents of the topic

C.18.4.4.4 Read-only Elements for topic

Table C-54 lists the read-only elements for this resource type.

Table C-54 Read-only Elements for topic

Element	Type	Description
`id`	Integer	Identifier for the topic
`parentId`	Integer	Identifier for the parent message
`forumId`	Integer	Identifier for the forum under which this topic is posted
`topicId`	Integer	Identifier for the topic under which this topic is posted
`createdBy`	String	ID of the user who created the topic
`author`	personReference	User information about the user who created the topic, including GUID, ID, display name, and a link to the profile icon (same user as `createdBy`)
`createdOn`	Date	Date on which the topic was created
`updatedBy`	String	User who lasted updated the topic
`updatedOn`	Date	Date on which the topic was last updated
`webUrl`	String	URL for direct access to the discussions server
`depth`	Integer	Depth in the hierarchy of messages
`messageCount`	Integer	Number of child messages under this topic
`numberOfReplies`	Integer	Number of replies to this topic
`favorite`	Boolean	Whether the topic is marked as a favorite for the user
`locked`	Boolean	Whether the topic is locked
`hidden`	Boolean	Whether the topic is hidden
`hasAttachment`	Boolean	Whether the topic has attachments

C.18.4.4.5 Resource Types Linked to From topic

Table C-55 lists the resource types that the client can link to from this resource.

Table C-55 Related Resource Types for topic

rel	resourceType
self	`urn:oracle:webcenter:discussions:forum:topic` `urn:oracle:webcenter:discussions:forum:topic:messages`

C.18.4.5 urn:oracle:webcenter:discussions:forum:topic:messages

Use this resource type to identify the URI to use to read (GET) and write (POST) discussion topic messages. The response from a GET operation includes each message in this collection of messages, and each message includes links used to operate on that message. The response from a POST operation includes the message that was created in this collection of messages and a link to operate on that message.

C.18.4.5.1 Navigation Paths to messages

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics
         messages

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics
               messages

C.18.4.5.2 Supported Methods for messages

The following methods are supported by this resource:

GET
- request - body: none, Parameters: startIndex, itemsPerPage (pagination)
- response - body: messages
POST
- request - body: message
- response - body: message

For more information, see Templates.

C.18.4.5.3 Resource Types Linked to From messages

Table C-56 lists the resource types that the client can link to from this resource.

Table C-56 Related Resource Types for messages

rel	resourceType
self	`urn:oracle:webcenter:discussions:forum:topic:messages` `urn:oracle:webcenter:discussions:forum:topic:message`

C.18.4.6 urn:oracle:webcenter:discussions:forum:topic:message

Use this resource type to identify the URI to use to read (GET), update (PUT), and delete (DELETE) a specific discussion topic message. The response from a GET operation includes the specific message identified by the URI. The response from a PUT operation includes the modified version of the message identified by the URI. The response from a DELETE operation is a 204.

C.18.4.6.1 Navigation Paths to message

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   forums
      topics
         messages
            message

resourceindex
   spaces
      spaces:resourceindex
         spaces:forums
            topics
               messages
                  message

C.18.4.6.2 Supported Methods for message

The following methods are supported by this resource:

GET
- request - body: none
- response - body: message
PUT
- request - body: message
- response - body: message
DELETE
- request - body: none
- response - body: none

C.18.4.6.3 Writable Elements for message

Table C-57 lists the writable elements for this resource.

Table C-57 Writable Elements for message

Element	Type	Required	Constraints	Description
`subject`	String	Yes	1 or more characters	Subject of this message
`body`	String	No	0 or more characters	Content of this message

C.18.4.6.4 Read-only Elements for message

Table C-58 lists the read-only elements for this resource.

Table C-58 Read-only Elements for message

Element	Type	Description
`id`	Integer	ID of the message
`parentId`	Integer	ID of the parent message
`forumId`	Integer	ID of the forum under which the message is posted
`topicId`	Integer	ID of the topic under which the message is posted
`createdBy`	String	ID of user that created the message
`author`	personReference	User information about the user that created the message, including GUID, ID, display name and a link to the profile icon (same user as `createdBy`)
`createdOn`	Date	Date on which the message was created
`updatedBy`	String	User that performed the last modification
`updatedOn`	Date	Date on which the message was last modified
`webUrl`	String	URL for direct access to the discussions server
`depth`	Integer	Depth in the hierarchy of messages
`messageCount`	Integer	Number of messages
`numberOfReplies`	Integer	Number of replies to this message
`hidden`	Boolean	True if this message is hidden
`hasAttachment`	Boolean	True if this message has attachments

C.18.4.6.5 Resource Types Linked to From message

Table C-59 lists the resource types that the client can link to from this resource.

Table C-59 Related Resource Types for message

rel	resourceType
self	`urn:oracle:webcenter:discussions:forum:topic:message` `urn:oracle:webcenter:discussions:forum:topic:messages`

C.19 Using the Lists REST API

Oracle WebCenter Portal provides a REST API to allow access to Lists functionality through interfaces other than the provided task flows. You can use the Lists REST API to perform the following actions:

Work with lists in a portal, such as retrieving a list of lists or adding a new list
Work with one list, such as retrieving or updating list metadata, or deleting the list
Work with rows in a list
Work with a list row, such as retrieving, updating, or deleting the row
Work with list columns, such as adding a column
Work with a list column, such as retrieving, updating, or deleting the column

This section describes the REST API methods associated with lists. It includes the following topics:

See Also:

For an introduction to the REST APIs, see Introduction to the WebCenter Portal REST APIs.

C.19.1 Entry Point for Lists

To get to the REST entry point for lists in a portal in WebCenter Portal, you search for the specific portal and retrieve the resource index. The corresponding href or template element provides the URI entry point, which retrieves the lists in the portal.

Navigate to the portal for which to retrieve the lists.
Retrieve the resource index:
```
urn:oracle:webcenter:resourceindex
```
Navigate to the returned href.
Search for the resource type. For example, for all the lists in a portal, search for:
```
urn:oracle:webcenter:space:lists
```

See Also:

For more information about the Resource Index, see Using the Resource Index

For more information about resource types, see Resource Type

C.19.2 Lists Resource Type Taxonomy

When the client has identified the entry point, it can then navigate through the resource type taxonomy to perform the required operations. The resource type taxonomy for lists is:

urn:oracle:webcenter:space:lists
urn:oracle:webcenter:space:list
   urn:oracle:webcenter:space:list:rows
   urn:oracle:webcenter:space:list:row
   urn:oracle:webcenter:space:list:columns
   urn:oracle:webcenter:space:list:column

C.19.3 Lists Security Considerations

You must be logged in to the REST service to access any of the Lists REST API methods. After that, the underlying service handles permission checking.

See Also:

For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.19.4 Lists Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.19.4.1 urn:oracle:webcenter:space:lists

The lists response provides a means of retrieving the lists in a given portal (GET) and adding lists to a portal (POST). This section includes the following topics:

C.19.4.1.1 Navigation Paths to lists

This section shows how the client can navigate through the hypermedia to access the lists resource:

urn:oracle:webcenter:resourceindex
   urn:oracle:webcenter:spaces
      urn:oracle:webcenter:space:resourceindex
         urn:oracle:webcenter:space:lists

C.19.4.1.2 Supported Methods for lists

The lists resource type supports the following methods:

C.19.4.1.2.1 Method (lists): `GET`

This method retrieves the lists in a portal.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists?q=name:equals:ProjectIssues&utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Request headers: [Accept = application/xml | application/json]
Request parameters - startIndex, itemsPerPage, q, projection
- q parameter for query, format 'q=attribute:operator:value', for example:
```
'q=name:equals:ProjectIssues'
```
  - Supported operators for Strings: equals, not.equals, contains, starts.with
  - Supported operators for Dates: equals, not.equals, greater.than, greater.than.or.equals, less.than, less.than.or.equals
  - May specify several conditions separated by semicolon (;)

Searchable attributes (Table C-60)

Table C-60 Searchable Attributes for lists GET Method

Element	Type	Description
name	string	Name of list
description	string	Description of list
creator	string	User who created list
created	date	Date the list was created
modifier	string	User who modified list
modified	date	Date the list was last modified

Response status: 200 [OK]
Response body: <lists>

Example:

<lists resourceType="urn:oracle:webcenter:space:lists">
   <links>
      <link resourceType="urn:oracle:webcenter:list:lists" 
         rel="self" href="opaque"/>
      <link template="opaque?startIndex={startIndex}&
         itemsPerPage={itemsPerPage}&q={searchTerms}&
         projection={projection}
         &stoken=FDgsOu7a2NTTM1cLJvnpkDXfihtHx5Q*"          resourceType="urn:oracle:webcenter:list:lists"/>
   </links>
   <items>
      <list resourceType="urn:oracle:webcenter:space:list">
         <links>
            <link resourceType="urn:oracle:webcenter:list" rel="self" 
               href="opaque" 
               capabilities="urn:oracle:webcenter:update 
               urn:oracle:webcenter:delete"/>
            <link resourceType="urn:oracle:webcenter:list:rows" 
               href="opaque" 
               capabilities="urn:oracle:webcenter:create"/>
            <link template="opaque?
               startIndex={startIndex}&
               itemsPerPage={itemsPerPage}&q={searchTerms}&
               stoken=FDgsOu7a2NTTM1cLJvnpkDXfihtHx5Q*" 
               resourceType="urn:oracle:webcenter:list:rows"/>
            <link resourceType="urn:oracle:webcenter:list:columns" 
               href="opaque"
               capabilities="urn:oracle:webcenter:create"/>
         </links>
         <id>/oracle/webcenter/list/scopedMD/
            se0dea180_e2c1_45ac_b08b_
            ba2c0b26aa72/lists/ProjectIssues.xml</id>
         <name>Project Issues</name>
         <description/>
      </list>
   </items>
</lists>

C.19.4.1.2.2 Method (lists): `POST`

This method creates a list in a portal.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: <list>

Writable elements (Table C-61)

Table C-61 Create List Writable Elements

Element	Type	Constraints	Description
name^Foot 8	string	—	Name of list
description	string	—	Description of list
columns^Foot 9	`urn:oracle:webcenter:space:list:columns`	1 to 30	List columns

^Footnote 8

Denotes required element

^Footnote 9

Denotes required element

Example:

<list>
   <name>RestExample</name>
   <description>Created using rest api</description>
   <columns>
      <items>
         <metaColumn>
            <name>No.</name>
            <dataType>number</dataType>
         </metaColumn>
         <metaColumn>
            <name>Description</name>
            <dataType>string</dataType>
         </metaColumn>
      </items>
   </columns>
</list>

Request headers: Content-Type = application/xml | application/json, [Accept = application/xml | application/json]
Response status: 201 [Created]
Response body: <list>

Retrieved elements (Table C-62)

Table C-62 Retrieved Elements from lists

Element	Type	Description
id	string	List ID
name	string	List name
description	string	List description
scope.guid	string	GUID of portal to which the list belongs
scope.name	string	Name of the portal to which the list belongs
creator	string	Name of the user who created the list
created	date	Date the list was created
modifier	string	Name of the user who last modified the list
modified	date	Date the list was last modified
columns	`urn:oracle:webcenter:space:list:columns`	List columns

Example:

<list resourceType="urn:oracle:webcenter:space:list">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list" rel="self" 
         href="http://host:port/rest/api/spaces/vs1/
         lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
         83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:update urn:oracle:webcenter:delete"/>
      <link template="http://host:port
         /rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
         s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_
         417b_a35f_fb03874979c0.xml)/rows?
         utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_
         w**&startIndex={startIndex}&itemsPerPage={itemsPerPage}
         &q={searchTerms}&utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         resourceType="urn:oracle:webcenter:space:list:rows" 
         href="http://host:port/rest/api/spaces/
         vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
         83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)/rows?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:create"/>
      <link resourceType="urn:oracle:webcenter:space:list:columns" 
         href="http://host:port/rest/api/spaces/
         vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
         83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)/columns?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_
         w**" capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:create"/>
   </links>
   <id>/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
      f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_fb03874979c0.xml</id>
   <name>RestExample</name>
   <description>Created using rest api</description>
   <scope>
      <guid>s355923f0_2f04_4fd0_83ad_f7dac2a7ceed</guid>
      <name>vs1</name>
   </scope>
   <creator>weblogic</creator>
   <author>
      <links>
         <link resourceType="urn:oracle:webcenter:people:person" 
            rel="via" href="http://host:port/
            rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists/
            @self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="image/png" 
            template="http://host:port/
            webcenter/profilephoto/45394133354538304630424
            33131444642464245304645333339453535423231/{size}?
            _xResourceMethod=wsrp" 
            resourceType="urn:oracle:webcenter:people:person" 
            rel="urn:oracle:webcenter:people:icon" 
            href="http://host:port/webcenter/
            profilephoto/4539413335453830463042433131444642464245304645
            333339453535423231/SMALL?_xResourceMethod=wsrp" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="text/html"
            resourceType="urn:oracle:webcenter:spaces:profile" 
            rel="alternate" href="http://host:port/
            webcenter/faces/oracle/webcenter/webcenterapp/view/pages/
            peopleconn/UserProfileGallery.jspx?wc.username=weblogic" 
            capabilities="urn:oracle:webcenter:read"/>
      </links>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </author>
   <created>2010-11-18T06:10:32.250-08:00</created>
   <modifier>weblogic</modifier>
   <modifiedByUser>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </modifiedByUser>
   <modified>2010-11-18T06:10:32.250-08:00</modified>
   <columns resourceType="urn:oracle:webcenter:space:list:columns">
      <links>
         <link resourceType="urn:oracle:webcenter:space:list:columns" 
            rel="self" 
            href="http://host:port/rest/api/spaces
            /vs1/lists/(/oracle/webcenter/list/scopedMD/
            s355923f0_2f04_4fd0_83ad_
            f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
            fb03874979c0.xml)/columns?utoken=
            FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read 
            urn:oracle:webcenter:create"/>
         <link resourceType="urn:oracle:webcenter:space:list"
            rel="urn:oracle:webcenter:parent" 
            href="http://host:port/
            rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
            s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/
            ls_c9cecbc7_756b_417b_a35f_fb03874979c0.xml)?
            utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**"/>
         </links>
         <items>
            <metaColumn resourceType=
               "urn:oracle:webcenter:space:list:column">
               <links>
                  <link resourceType="urn:oracle:webcenter:space:
                     list:column" rel="self 
                     "href="http://host:port/
                     rest/api/spaces/vs1/lists/
                     (/oracle/webcenter/list/scopedMD/
                     s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/
                     lists/ls_c9cecbc7_756b_417b_a35f_
                     fb03874979c0.xml)/columns/
                     (lco_9bdd1418_6004_40ba_a052_04e8335b7ee8)?
                     utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
                     capabilities="urn:oracle:webcenter:read 
                     urn:oracle:webcenter:update 
                     urn:oracle:webcenter:delete"/>
               </links>
               <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
               <name>No.</name>
               <dataType>number</dataType>
               <required>false</required>
               <displayLength>10</displayLength>
               <format>number</format>
               <allowLinks>false</allowLinks>
            </metaColumn>
            <metaColumn resourceType=
               "urn:oracle:webcenter:space:list:column">
               <links>
                  <link resourceType=
                     "urn:oracle:webcenter:space:list:column" 
                     rel="self"
                     href="http://host:port/
                     rest/api/spaces/vs1/lists/(/oracle/
                     webcenter/list/scopedMD/
                     s355923f0_2f04_4fd0_83ad_
                     f7dac2a7ceed/lists/ls_c9cecbc7_756b_
                     417b_a35f_fb03874979c0.xml)/columns/
                     (lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24)?
                     utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
                     capabilities="urn:oracle:webcenter:read 
                     urn:oracle:webcenter:update
                     urn:oracle:webcenter:delete"/>
            </links>
            <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
            <name>Description</name>
            <dataType>string</dataType>
            <required>false</required>
            <maxLength>500</maxLength>
            <displayLength>20</displayLength>
            <allowLinks>false</allowLinks>
            <editLines>1</editLines>
         </metaColumn>
      </items>
   </columns>
</list>

C.19.4.1.3 Resource Types Linked to from lists

Table C-63 lists the resource types that the client can link to from the lists resource.

Table C-63 Resource Types Linked to from lists

rel	resourceType
self	`urn:oracle:webcenter:space:lists`
Related	`urn:oracle:webcenter:space:list`

C.19.4.2 urn:oracle:webcenter:space:list

The list response provides a means of retrieving, updating, and deleting an individual list. This section includes the following topics:

C.19.4.2.1 Navigation Paths to list

This section shows how the client can navigate through the hypermedia to access the list resource:

urn:oracle:webcenter:resourceindex 
   urn:oracle:webcenter:spaces 
      urn:oracle:webcenter:space:resourceindex 
         urn:oracle:webcenter:space:lists 
            urn:oracle:webcenter:space:list

C.19.4.2.2 Supported Methods for list

The list resource type supports the following methods:

C.19.4.2.3 Method (list): `GET`

Use this method to retrieve a list.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
5fb62dc3514d.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Request headers: [Accept = application/xml | application/json]
Response status: 200 [OK]
Response body: <list>

Retrieved elements (Table C-64)

Table C-64 Retrieved Elements for list

Element	Type	Description
id	string	ID of the list
name	string	Name of the list
description	string	Description of the list
scope.guid	string	GUID of the portal to which the list belongs
scope.name	string	Name of the portal to which the list belongs
creator	string	User who created the list
created	Date	Date on which the list was created
modifier	string	User who last modified the list
modified	Date	Date on which the list was last modified
columns	`urn:oracle:webcenter:space:list:columns`	The columns that make up the list

For example:

<list resourceType="urn:oracle:webcenter:space:list">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list" rel="self" 
         href="http://host:port/rest/api/spaces/vs1/
         lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
         f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:update 
         urn:oracle:webcenter:delete"/>
      <link template="http://host:port
         /rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
         s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_
         417b_a35f_fb03874979c0.xml)/rows?
         utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**&
         startIndex={startIndex}&itemsPerPage={itemsPerPage}&q=
         {searchTerms}&utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**"
         resourceType="urn:oracle:webcenter:space:list:rows" 
         href="http://host:port/rest/api/
         spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_
         2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)/rows?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:create"/>
      <link resourceType="urn:oracle:webcenter:space:list:columns" 
         href="http://host:port/rest/api/spaces/
         vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
         83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)/columns?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_
         w**" capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:create"/>
   </links>
   <id>/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
      f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_fb03874979c0.xml</id>
   <name>RestExample</name>
   <description>Created using rest api</description>
   <scope>
      <guid>s355923f0_2f04_4fd0_83ad_f7dac2a7ceed</guid>
      <name>vs1</name>
   </scope>
   <creator>weblogic</creator>
   <author>
      <links>
         <link resourceType="urn:oracle:webcenter:people:person" 
            rel="via" href="http://host:port/
            rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists/
            @self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**"
            capabilities="urn:oracle:webcenter:read"/>
         <link type="image/png"
            template="http://host:port/
            webcenter/profilephoto/4539413335453830463042433131444
            642464245304645333339453535423231/{size}?
            _xResourceMethod=wsrp" 
            resourceType="urn:oracle:webcenter:people:person" 
            rel="urn:oracle:webcenter:people:icon" 
            href="http://host:port/
            webcenter/profilephoto/4539413335453830463042433131444
            642464245304645333339453535423231/SMALL?
            _xResourceMethod=wsrp" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="text/html" 
            resourceType="urn:oracle:webcenter:spaces:profile" 
            rel="alternate" href="http://host:port/
            webcenter/faces/oracle/webcenter/webcenterapp/view/pages/
            peopleconn/UserProfileGallery.jspx?wc.username=weblogic" 
            capabilities="urn:oracle:webcenter:read"/>
      </links>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </author>
   <created>2010-11-18T06:10:32.250-08:00</created>
   <modifier>weblogic</modifier>
   <modifiedByUser>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </modifiedByUser>
   <modified>2010-11-18T06:10:32.250-08:00</modified>
   <columns resourceType="urn:oracle:webcenter:space:list:columns">
      <links>
         <link resourceType="urn:oracle:webcenter:space:list:columns" 
            rel="self" href="http://host:port/
            rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
            s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_
            756b_417b_a35f_fb03874979c0.xml)/
            columns?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read 
            urn:oracle:webcenter:create"/>
         <link resourceType="urn:oracle:webcenter:space:list" 
            rel="urn:oracle:webcenter:parent" 
            href="http://host:port/rest/api/spaces/
            vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_
            4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
            fb03874979c0.xml)?utoken=
            FKld8lalI3QRdi8TgQkOCGEzxL5x_w**"/>
      </links>
      <items>
         <metaColumn resourceType=
            "urn:oracle:webcenter:space:list:column">
            <links>
               <link resourceType=
                  "urn:oracle:webcenter:space:list:column" 
                  rel="self" 
                   href="http://host:port/
                  rest/api/spaces/vs1/lists/(/oracle/webcenter/
                  list/scopedMD/s355923f0_2f04_4fd0_83ad_
                  f7dac2a7ceed/lists/ls_c9cecbc7_
                  756b_417b_a35f_fb03874979c0.xml)/columns/(lco_
                  9bdd1418_6004_40ba_a052_04e8335b7ee8)?
                  utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
                  capabilities="urn:oracle:webcenter:read 
                  urn:oracle:webcenter:update 
                  urn:oracle:webcenter:delete"/>
            </links>
            <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
            <name>No.</name>
            <dataType>number</dataType>
            <required>false</required>
            <displayLength>10</displayLength>
            <format>number</format>
            <allowLinks>false</allowLinks>
         </metaColumn>
         <metaColumn resourceType=
            "urn:oracle:webcenter:space:list:column">
            <links>
               <link resourceType=
                  "urn:oracle:webcenter:space:list:column" 
                  rel="self" 
                  href="http://host:port
                  /rest/api/spaces/vs1/lists/(/oracle/webcenter/
                  list/scopedMD/s355923f0_2f04_4fd0_83ad_
                  f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
                  fb03874979c0.xml)/columns/(lco_3a31fd20_24f1_
                  4422_99fd_c00d7bed4b24)?
                  utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
                  capabilities="urn:oracle:webcenter:read
                  urn:oracle:webcenter:update                   urn:oracle:webcenter:delete"/>
            </links>
            <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
            <name>Description</name>
            <dataType>string</dataType>
            <required>false</required>
            <maxLength>500</maxLength>
            <displayLength>20</displayLength>
            <allowLinks>false</allowLinks>
            <editLines>1</editLines>
         </metaColumn>
      </items>
   </columns>
</list>

C.19.4.2.4 Method (list): `PUT`

Use this method to update a list name or description.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
5fb62dc3514d.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: <list>
Writable elements for list (Table C-65)

Table C-65 Writable Elements for list

Element Type Required Constraints Description

name^Foot 10

string

Yes

1 or more characters

Name of this list

description

string

No

none

Description of this list

^Footnote 10

Denotes required element

For example:

<list>
   <name>RestExampleUpdate</name>
   <description>Updated using rest api</description>
</list>

Request headers: Content-Type = application/xml | application/json, [Accept = application/xml | application/json]
Response status: 200 [OK]
Response body: <list>

C.19.4.2.5 Method (list): `DELETE`

Use this method to delete a list.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
5fb62dc3514d.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Response status: 204 [No Content]
Response body: none

C.19.4.2.6 Resource Types Linked to from list

Table C-66 lists the resource types that the client can link to from the list resource.

Table C-66 Resource Types Linked to from list

rel	resourceType
self	`urn:oracle:webcenter:space:list`
Related	`urn:oracle:webcenter:space:list:rows`
Related	`urn:oracle:webcenter:space:list:columns`

C.19.4.3 urn:oracle:webcenter:space:list:rows

The rows response provides a means of retrieving and adding rows to a list. This section includes the following topics:

C.19.4.3.1 Navigation Paths to rows

This section shows how the client can navigate through the hypermedia to access the rows resource:

urn:oracle:webcenter:resourceindex
   urn:oracle:webcenter:spaces
      urn:oracle:webcenter:space:resourceindex
         urn:oracle:webcenter:space:lists
            urn:oracle:webcenter:space:list
               urn:oracle:webcenter:space:list:rows

C.19.4.3.2 Supported Methods for rows

The rows resource type supports the following methods:

Method (rows): GET
Method (rows): POST

Method (rows): GET

Use this method to retrieve list rows.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
5fb62dc3514d.xml)/rows?q=lco_9bdd1418_6004_40ba_a052_
04e8335b7ee8:equals:2&utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Request headers: [Accept = application/xml | application/json]
Request parameters - startIndex, itemsPerPage, q, projection
- q parameter for query, format 'q=columnId:operator:value', for example:
```
'q=lco_9bdd1418_6004_40ba_a052_04e8335b7ee8:equals:2'
```
  - Supported operators for Strings: equals, not.equals, contains, starts.with
  - Supported operators for Numbers, Dates: equals, not.equals, greater.than, greater.than.or.equals, less.than, less.than.or.equals
  - May specify several conditions separated by semi-colon (;)
Searchable attributes for rows: Rows are searchable by column values.
Response status: 200 [OK]
Response body: <rows>

For example:

<rows resourceType="urn:oracle:webcenter:space:list:rows">
   <links>
      <link template="http://host:port/
         rest/api/spaces/vs1/lists/(/oracle/webcenter/list/
         scopedMD/s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_
         c9cecbc7_756b_417b_a35f_fb03874979c0.xml)/rows?
         utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**&
         startIndex={startIndex}&itemsPerPage={itemsPerPage}&
         q={searchTerms}&utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         resourceType="urn:oracle:webcenter:space:list:rows" rel="self" 
         href="http://host:port/rest/api/spaces/
         vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
         83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)/rows?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:create"/>
      <link resourceType="urn:oracle:webcenter:space:list" 
         rel="urn:oracle:webcenter:parent" 
         href="http://host:port/rest/api/spaces/
         vs1/lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
         83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**"/>
   </links>
   <itemsPerPage>1</itemsPerPage>
   <startIndex>0</startIndex>
   <items>
      <row resourceType="urn:oracle:webcenter:space:list:row">
         <links>
            <link resourceType="urn:oracle:webcenter:space:list:row" 
               rel="self" href="http://host:port/
               rest/api/spaces/vs1/lists/(/oracle/webcenter/list/
               scopedMD/s355923f0_2f04_4fd0_83ad_
               f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
               fb03874979c0.xml)/rows/(lr_a14d427f_8515_4c82_956f_
               a60e6e08668c)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
               capabilities="urn:oracle:webcenter:read 
               urn:oracle:webcenter:update 
               urn:oracle:webcenter:delete"/>
         </links>
         <id>lr_a14d427f_8515_4c82_956f_a60e6e08668c</id>
         <listId>/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_
            83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
            fb03874979c0.xml</listId>
         <scope>s355923f0_2f04_4fd0_83ad_f7dac2a7ceed</scope>
         <creator>weblogic</creator>
         <author>
            <links>
               <link resourceType=
                  "urn:oracle:webcenter:people:person" 
                  rel="via" 
                  href="http://host:port/
                  rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/
                  lists/@self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_
                  w**" capabilities="urn:oracle:webcenter:read"/>
               <link type="image/png" 
                  template="http://host:port/
                  webcenter/profilephoto/45394133354538304630424
                  33131444642464245304645333339453535423231/
                  {size}?_xResourceMethod=wsrp" 
                  resourceType="urn:oracle:webcenter:people:person" 
                  rel="urn:oracle:webcenter:people:icon" 
                  href="http://host:port/
                  webcenter/profilephoto/45394133354538304630424
                  33131444642464245304645333339453535423231/SMALL?
                  _xResourceMethod=wsrp" 
                  capabilities="urn:oracle:webcenter:read"/>
               <link type="text/html" 
                  resourceType="urn:oracle:webcenter:spaces:
                  profile" rel="alternate" 
                  href="http://host:port/
                  webcenter/faces/oracle/webcenter/webcenterapp/
                  view/pages/peopleconn/UserProfileGallery.jspx?
                  wc.username=weblogic" 
                  capabilities="urn:oracle:webcenter:read"/>
            </links>
            <displayName>weblogic</displayName>
            <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
            <id>weblogic</id>
         </author>
         <created>2010-11-18T07:12:06.599-08:00</created>
         <modifier>weblogic</modifier>
         <modifiedByUser>
            <links>
               <link resourceType=
                  "urn:oracle:webcenter:people:person" rel="via" 
                  href="http://host:port/rest/
                  api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists
                  /@self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
                  capabilities="urn:oracle:webcenter:read"/>
               <link type="image/png" 
                  template="http://host:port/
                  webcenter/profilephoto/45394133354538304630424
                  33131444642464245304645333339453535423231/
                  {size}?_xResourceMethod=wsrp" 
                  resourceType="urn:oracle:webcenter:people:person" 
                  rel="urn:oracle:webcenter:people:icon" 
                  href="http://host:port/
                  webcenter/profilephoto/45394133354538304630424
                  33131444642464245304645333339453535423231/SMALL?
                  _xResourceMethod=wsrp" 
                  capabilities="urn:oracle:webcenter:read"/>
               <link type="text/html" 
                  resourceType="urn:oracle:webcenter:spaces:
                  profile" rel="alternate" 
                  href="http://host:port/
                  webcenter/faces/oracle/webcenter/webcenterapp/
                  view/pages/peopleconn/UserProfileGallery.jspx?
                  wc.username=weblogic" 
                  capabilities="urn:oracle:webcenter:read"/>
            </links>
            <displayName>weblogic</displayName>
            <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
            <id>weblogic</id>
         </modifiedByUser>
         <modified>2010-11-18T07:12:06.599-08:00</modified>
         <columns>
            <column>
               <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
               <name>No.</name>
               <value>1.0</value>
            </column>
            <column>
               <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
               <name>Description</name>
               <value>test</value>
            </column>
         </columns>
      </row>
   </items>
</rows>

Method (rows): POST

Use this method to create a row in a list.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
5fb62dc3514d.xml)/rows?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: <row>
Writable elements (Table C-67)

Table C-67 Writable Elements for rows

Element Type Constraints Description

columns.column.id^Foot 11

string

—

Column ID

columns.column.value^Foot 12

string

Valid value for column data type

Column value

^Footnote 11

Denotes required element

^Footnote 12

Denotes required element

For example:

<row>
   <columns>
      <column>
         <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
         <value>1</value>
      </column>
      <column>
         <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
         <value>test</value>
      </column>
   </columns>
</row>

Request headers: Content-Type = application/xml | application/json, [Accept = application/xml | application/json]
Response status: 201 [Created]
Response body: <row>

Retrieved elements (Table C-68)

Table C-68 Retrieved Elements for rows

Element	Type	Description
id	string	Row ID
list id	string	List ID
scope	string	GUID of portal to which list belongs
creator	string	Person who created the list
created	date	Date the list was created
modifier	string	Last user to modify the list
modified	date	Date the list was last modified
columns	—	Column values

For example:

<row resourceType="urn:oracle:webcenter:space:list:row">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list:row" rel="self" 
         href="http://host:port/rest/api/spaces/vs1/
         lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
         f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
         5fb62dc3514d.xml)/rows/(lr_4cc07327_49cb_4cd5_a270_
         182ddcc8db4a)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:update urn:oracle:webcenter:delete"/>
   </links>
   <id>lr_4cc07327_49cb_4cd5_a270_182ddcc8db4a</id>
   <listId>/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
      f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
      5fb62dc3514d.xml</listId>
   <scope>s355923f0_2f04_4fd0_83ad_f7dac2a7ceed</scope>
   <creator>weblogic</creator>
   <author>
      <links>
         <link resourceType="urn:oracle:webcenter:people:person" 
            rel="via" href="http://host:port
            /rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists/
            @self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="image/png" 
            template="http://host:port/
            webcenter/profilephoto/4539413335453830463042433131
            444642464245304645333339453535423231/{size}?
            _xResourceMethod=wsrp" 
            resourceType="urn:oracle:webcenter:people:person" 
            rel="urn:oracle:webcenter:people:icon" 
            href="http://host:port/webcenter/
            profilephoto/453941333545383046304243313144464246424530
            4645333339453535423231/SMALL?_xResourceMethod=wsrp" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="text/html" 
            resourceType="urn:oracle:webcenter:spaces:profile" 
            rel="alternate" href="http://host:port/
            webcenter/faces/oracle/webcenter/webcenterapp/view/pages/
            peopleconn/UserProfileGallery.jspx?wc.username=weblogic" 
            capabilities="urn:oracle:webcenter:read"/>
      </links>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </author>
   <created>2010-11-17T06:34:25.042-08:00</created>
   <modifier>weblogic</modifier>
   <modifiedByUser>
      <links>
         <link resourceType="urn:oracle:webcenter:people:person" 
            rel="via" href="http://host:port/
            rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists/
            @self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="image/png" 
            template="http://host:port/
            webcenter/profilephoto/4539413335453830463042433131
            444642464245304645333339453535423231/{size}?
            _xResourceMethod=wsrp" 
            resourceType="urn:oracle:webcenter:people:person" 
            rel="urn:oracle:webcenter:people:icon" 
            href="http://host:port/webcenter/
            profilephoto/453941333545383046304243313144464246424530
            4645333339453535423231/SMALL?_xResourceMethod=wsrp" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="text/html" 
            resourceType="urn:oracle:webcenter:spaces:profile" 
            rel="alternate" href="http://host:port/
            webcenter/faces/oracle/webcenter/webcenterapp/view/pages/
            peopleconn/UserProfileGallery.jspx?wc.username=weblogic" 
            capabilities="urn:oracle:webcenter:read"/>
      </links>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </modifiedByUser>
      <modified>2010-11-17T06:34:25.042-08:00</modified>
   <columns>
      <column>
         <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
         <name>No.</name>
         <value>1.0</value>
      </column>
      <column>
         <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
         <name>Description</name>
         <value>test</value>
      </column>
   </columns>
</row>

C.19.4.3.3 Resource Types Linked to from rows

Table C-69 lists the resource types that the client can link to from the rows resource.

Table C-69 Resource Types Linked to from rows

rel	resourceType
self	`urn:oracle:webcenter:space:list.rows`
parent	`urn:oracle:webcenter:space:list`
Related	`urn:oracle:webcenter:space:list:row`

C.19.4.4 urn:oracle:webcenter:space:list:row

The row response provides a means of retrieving and adding, and deleting an individual list row. This section includes the following topics:

C.19.4.4.1 Navigation Paths to row

This section shows how the client can navigate through the hypermedia to access the row resource:

urn:oracle:webcenter:resourceindex
   urn:oracle:webcenter:spaces
      urn:oracle:webcenter:space:resourceindex
         urn:oracle:webcenter:space:lists
            urn:oracle:webcenter:space:list
               urn:oracle:webcenter:space:list:rows
                  urn:oracle:webcenter:space:list:row

C.19.4.4.2 Supported Methods for row

The row resource type supports the following methods:

C.19.4.4.3 Method (row): `GET`

Use this method to retrieve data from a list row.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/rows/(lr_a14d427f_8515_4c82_956f_
a60e6e08668c)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Request headers: [Accept = application/xml | application/json]
Response status: 200 [OK]
Response body: <row>

Retrieved elements (Table C-70)

Table C-70 Retrieved Elements for row

Element	Type	Description
id	string	ID of the row
listId	string	ID of the parent list
scope	string	GUID of the portal to which the list belongs
creator	string	User who created the row
created	Date	Date on which the row was created
modifier	string	User who last modified the row
modified	Date	Date on which the row was last modified
columns	`urn:oracle:webcenter:space:list:columns`	Column values

For example:

<row resourceType="urn:oracle:webcenter:space:list:row">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list:row" 
         rel="self" href="http://host:port/
         rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD
         /s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_bb806754_0652_
         4d49_9354_5fb62dc3514d.xml)/rows/(lr_4cc07327_49cb_4cd5_a270_
         182ddcc8db4a)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:update urn:oracle:webcenter:delete"/>
   </links>
   <id>lr_4cc07327_49cb_4cd5_a270_182ddcc8db4a</id>
   <listId>/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
      f7dac2a7ceed/lists/ls_bb806754_0652_4d49_9354_
      5fb62dc3514d.xml</listId>
   <scope>s355923f0_2f04_4fd0_83ad_f7dac2a7ceed</scope>
   <creator>weblogic</creator>
   <author>
      <links>
         <link resourceType="urn:oracle:webcenter:people:person" 
            rel="via" href="http://host:port/
            rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists/
            @self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="image/png" 
            template="http://host:port/webcenter/
            profilephoto/453941333545383046304243313144464246424530
            4645333339453535423231/{size}?_xResourceMethod=wsrp" 
            resourceType="urn:oracle:webcenter:people:person" 
            rel="urn:oracle:webcenter:people:icon" 
            href="http://host:port/webcenter/
            profilephoto/453941333545383046304243313144464246424530
            4645333339453535423231/SMALL?_xResourceMethod=wsrp" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="text/html" 
            resourceType="urn:oracle:webcenter:spaces:profile" 
            rel="alternate" href="http://host:port/
            webcenter/faces/oracle/webcenter/webcenterapp/view/pages/
            peopleconn/UserProfileGallery.jspx?wc.username=weblogic" 
            capabilities="urn:oracle:webcenter:read"/>
      </links>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </author>
   <created>2010-11-17T06:34:25.042-08:00</created>
   <modifier>weblogic</modifier>
   <modifiedByUser>
      <links>
         <link resourceType="urn:oracle:webcenter:people:person" 
            rel="via" href="http://host:port/
            rest/api/people/E9A35E80F0BC11DFBFBE0FE339E55B21/lists/
            @self?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="image/png" 
            template="http://host:port/webcenter/
            profilephoto/453941333545383046304243313144464246424530
            4645333339453535423231/{size}?_xResourceMethod=wsrp" 
            resourceType="urn:oracle:webcenter:people:person" 
            rel="urn:oracle:webcenter:people:icon" 
            href="http://host:port/webcenter/
            profilephoto/453941333545383046304243313144464246424530
            4645333339453535423231/SMALL?_xResourceMethod=wsrp" 
            capabilities="urn:oracle:webcenter:read"/>
         <link type="text/html" 
            resourceType="urn:oracle:webcenter:spaces:profile" 
            rel="alternate" href="http://host:port/
            webcenter/faces/oracle/webcenter/webcenterapp/view/pages/
            peopleconn/UserProfileGallery.jspx?wc.username=weblogic" 
            capabilities="urn:oracle:webcenter:read"/>
      </links>
      <displayName>weblogic</displayName>
      <guid>E9A35E80F0BC11DFBFBE0FE339E55B21</guid>
      <id>weblogic</id>
   </modifiedByUser>
   <modified>2010-11-17T06:34:25.042-08:00</modified>
   <columns>
      <column>
         <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
         <name>No.</name>
         <value>1.0</value>
      </column>
      <column>
         <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
         <name>Description</name>
         <value>test</value>
      </column>
   </columns>
</row>

C.19.4.4.4 Method (row): `PUT`

Use this method to update row data.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/rows/(lr_a14d427f_8515_4c82_956f_
a60e6e08668c)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: <row>
Writable elements (Table C-71)

Table C-71 Writable Elements for row

Element Type Constraints Description

columns.column.id^Foot 13

string

—

Column ID

columns.column.value^Foot 14

string

valid value for column data type

Column value

^Footnote 13

Denotes required element

^Footnote 14

Denotes required element

For example:

<row>
   <columns>
      <column>
         <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
         <value>1</value>
      </column>
      <column>
         <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
         <value>test</value>
      </column>
   </columns>
</row>

Request headers: Content-Type = application/xml | application/json, [Accept = application/xml | application/json]
Response status: 200 [OK]
Response body: <row>

C.19.4.4.5 Method (row): `DELETE`

Use this method to delete a list row.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/rows/(lr_a14d427f_8515_4c82_956f_
a60e6e08668c)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Response status: 204 [No Content]
Response body: none

C.19.4.4.6 Resource Types Linked to from row

Table C-72 lists the resource types that the client can link to from the row resource.

Table C-72 Resource Types Linked to from row

rel	resourceType
self	`urn:oracle:webcenter:space:list:row`

C.19.4.5 urn:oracle:webcenter:space:list:columns

The columns response provides a means of retrieving and adding list columns. This section includes the following topics:

C.19.4.5.1 Navigation Paths to columns

This section shows how the client can navigate through the hypermedia to access the columns resource:

urn:oracle:webcenter:resourceindex
   urn:oracle:webcenter:spaces
      urn:oracle:webcenter:space:resourceindex
         urn:oracle:webcenter:space:lists
            urn:oracle:webcenter:space:list
               urn:oracle:webcenter:space:list:columns

C.19.4.5.2 Supported Methods for columns

The columns resource type supports the following methods:

C.19.4.5.3 Method (columns): `GET`

Use this method to retrieve columns in a list.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/columns?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Request headers: [Accept = application/xml | application/json]
Request parameters: none
Response status: 200 [OK]
Response body: <metaColumns>

For example:

<metaColumns resourceType="urn:oracle:webcenter:space:list:columns">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list:columns" 
         rel="self" href="http://host:port/
         rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
         s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_
         417b_a35f_fb03874979c0.xml)/columns?
         utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:create"/>
      <link resourceType="urn:oracle:webcenter:space:list" 
         rel="urn:oracle:webcenter:parent" 
         href="http://host:port/rest/api/spaces/vs1/
         lists/(/oracle/webcenter/list/scopedMD/s355923f0_2f04_4fd0_83ad_
         f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
         fb03874979c0.xml)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**"/>
   </links>
   <items>
      <metaColumn resourceType="urn:oracle:webcenter:space:list:column">
         <links>
            <link resourceType="urn:oracle:webcenter:space:list:column" 
               rel="self" href="http://host:port/
               rest/api/spaces/vs1/lists/(/oracle/webcenter/list/
               scopedMD/s355923f0_2f04_4fd0_83ad_
               f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
               fb03874979c0.xml)/columns/(lco_9bdd1418_6004_40ba_
               a052_04e8335b7ee8)?
               utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
               capabilities="urn:oracle:webcenter:read 
               urn:oracle:webcenter:update 
               urn:oracle:webcenter:delete"/>
         </links>
         <id>lco_9bdd1418_6004_40ba_a052_04e8335b7ee8</id>
         <name>No.</name>
         <dataType>number</dataType>
         <required>false</required>
         <displayLength>10</displayLength>
         <format>number</format>
         <allowLinks>false</allowLinks>
      </metaColumn>
      <metaColumn resourceType="urn:oracle:webcenter:space:list:column">
         <links>
            <link resourceType="urn:oracle:webcenter:space:list:column" 
               rel="self" href="http://host:port/
               rest/api/spaces/vs1/lists/(/oracle/webcenter/list/
               scopedMD/s355923f0_2f04_4fd0_83ad_
               f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
               fb03874979c0.xml)/columns/(lco_3a31fd20_24f1_4422_
               99fd_c00d7bed4b24)?
               utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
               capabilities="urn:oracle:webcenter:read 
               urn:oracle:webcenter:update 
               urn:oracle:webcenter:delete"/>
         </links>
         <id>lco_3a31fd20_24f1_4422_99fd_c00d7bed4b24</id>
         <name>Description</name>
         <dataType>string</dataType>
         <required>false</required>
         <maxLength>500</maxLength>
         <displayLength>20</displayLength>
         <allowLinks>false</allowLinks>
         <editLines>1</editLines>
      </metaColumn>
   </items>
</metaColumns>

C.19.4.5.4 Method (columns): `POST`

Use this method to create a column in a list.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/columns?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: <metaColumn>

Writable elements (Table C-73)

Table C-73 Writable Elements for columns

Element	Type	Constraints	Description
name^Foot 15	string	—	The name of the column
dataType^Foot 16	string	`string` `number` `datetime` `boolean` `person` `image` `richtext`	The data type of the column
required	boolean	`true` `false`	Whether a value is required for the column
defaultValue	data type of column	Object must match data type	The default value of the column
maxLength	int	Valid only for `string` data type	The maximum length for a string value
rangeLow	int	Valid only for `number` data type	The low range value for a `number` data type
rangeHigh	int	Valid only for `number` data type	The high range value for a `number` data type
format	string	For `number` data type: number currency percent For `datetime` data type: date time both	The format of the column
allowLinks	boolean	`true` `false` Valid only for `string` data type	Whether a hyperlink can be specified for a column value
linkTarget	string	`_blank` `_self` Valid only if `allowLinks=true`	`_blank` opens link in a new window, `_self` opens link in the same window
editLines	int	Valid only for `string` data type	The number of lines when editing a column value (default=1)
peopleScope	string	GLOBAL SUB_SCOPE Valid only for `person` data type	Whether valid users are all users in directory or members of the portal that contains the list
displayWidth	int	—	Display width of column in pixels
hint	string	—	Hint displayed to help user when entering column value

^Footnote 15

Denotes required element

^Footnote 16

Denotes required element

For example:

<metaColumn>
   <name>Notes</name>
   <dataType>richtext</dataType>
</metaColumn

Request headers: Content-Type = application/xml | application/json, [Accept = application/xml | application/json]
Response status: 201 [Created]
Response body: <metaColumn>

Retrieved elements (Table C-74)

Table C-74 Retrieved Elements from columns

Element	Type	Description
id	string	Column ID
name	string	The name of the column
dataType	string	The data type of the column
required	boolean	Whether a value is required for the column
defaultValue	data type of column	The default value of the column
maxLength	int	The maximum length for a string value
rangeLow	int	The low range value for a `number` data type
rangeHigh	int	The high range value for a `number` data type
format	string	The format of the column
allowLinks	boolean	Whether a hyperlink can be specified for a column value
linkTarget	string	`_blank` opens link in a new window, `_self` opens link in the same window
editLines	int	The number of lines when editing a column value (default=1)
peopleScope	string	Whether valid users are all users in directory or members of the portal that contains the list
displayWidth	int	Display width of column in pixels
hint	string	Hint displayed to help user when entering column value

For example:

<metaColumn resourceType="urn:oracle:webcenter:space:list:column">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list:column" 
         rel="self" href="http://host:port/
         rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
         s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/
         ls_c9cecbc7_756b_417b_a35f_fb03874979c0.xml)/columns/
         (lco_fe2b9856_32f3_449a_a277_18dc7f6a779e)?
         utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:update urn:oracle:webcenter:delete"/>
   </links>
   <id>lco_fe2b9856_32f3_449a_a277_18dc7f6a779e</id>
   <name>Notes</name>
   <dataType>richtext</dataType>
   <required>false</required>
   <displayLength>20</displayLength>
   <allowLinks>false</allowLinks>
</metaColumn>

C.19.4.5.5 Resource Types Linked to from columns

Table C-75 lists the resource types that the client can link to from the columns resource.

Table C-75 Resource Types Linked to from columns

rel	resourceType
self	`urn:oracle:webcenter:space:list.columns`
parent	`urn:oracle:webcenter:space:list`
Related	`urn:oracle:webcenter:space:list:column`

C.19.4.6 urn:oracle:webcenter:space:list:column

The column response provides a means of retrieving, adding, and deleting an individual list column. This section includes the following topics:

C.19.4.6.1 Navigation Paths to column

This section shows how the client can navigate through the hypermedia to access the column resource:

urn:oracle:webcenter:resourceindex
   urn:oracle:webcenter:spaces
      urn:oracle:webcenter:space:resourceindex
         urn:oracle:webcenter:space:lists
            urn:oracle:webcenter:space:list
               urn:oracle:webcenter:space:list:columns
                  urn:oracle:webcenter:space:list:column

C.19.4.6.2 Supported Methods for column

The column resource type supports the following methods:

Method (column): GET
Method (column): PUT
Method (column): DELETE

Method (column): GET

Use this method to retrieve a list column.

Resource URI. for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/columns/(lco_fe2b9856_32f3_449a_a277_
18dc7f6a779e)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Request headers: [Accept = application/xml | application/json]
Response status: 200 [OK]
Response body: <metaColumn>

Retrieved elements (Table C-76)

Table C-76 column Retrieved Elements

Element	Type	Description
id	string	Column ID
name	string	The name of the column
dataType	string	The data type of the column
required	boolean	Whether a value is required for the column
defaultValue	data type of column	The default value of the column
maxLength	int	The maximum length for a string value
rangeLow	int	The low range value for a `number` data type
rangeHigh	int	The high range value for a `number` data type
format	string	The format of the column
allowLinks	boolean	Whether a hyperlink can be specified for a column value
linkTarget	string	`_blank` opens link in a new window, `_self` opens link in the same window
editLines	int	The number of lines when editing a column value (default=1)
peopleScope	string	Whether valid users are all users in directory or members of the portal that contains the list
displayWidth	int	Display width of column in pixels
hint	string	Hint displayed to help user when entering column value

For example:

<metaColumn resourceType="urn:oracle:webcenter:space:list:column">
   <links>
      <link resourceType="urn:oracle:webcenter:space:list:column" 
         rel="self" href="http://host:port/
         rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
         s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/
         ls_c9cecbc7_756b_417b_a35f_fb03874979c0.xml)/
         columns/(lco_fe2b9856_32f3_449a_a277_18dc7f6a779e)?
         utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**" 
         capabilities="urn:oracle:webcenter:read 
         urn:oracle:webcenter:update urn:oracle:webcenter:delete"/>
   </links>
   <id>lco_fe2b9856_32f3_449a_a277_18dc7f6a779e</id>
   <name>Notes</name>
   <dataType>richtext</dataType>
   <required>false</required>
   <displayLength>20</displayLength>
   <allowLinks>false</allowLinks>
</metaColumn>

Method (column): PUT

Use this method to update column data.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/columns/(lco_fe2b9856_32f3_449a_a277_
18dc7f6a779e)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: <metacolumn>

Writable elements (Table C-77)

Table C-77 column Writable Elements

Element	Type	Constraints	Description
name^Foot 17	string	—	The name of the column
dataType^Foot 18	string	`string` `number` `datetime` `boolean` `person` `image` `richtext`	The data type of the column
required	boolean	`true` `false`	Whether a value is required for the column
defaultValue	data type of column	Object must match data type	The default value of the column
maxLength	int	Valid only for `string` data type	The maximum length for a string value
rangeLow	int	Valid only for `number` data type	The low range value for a `number` data type
rangeHigh	int	Valid only for `number` data type	The high range value for a `number` data type
format	string	For `number` data type: number currency percent For `datetime` data type: date time both	The format of the column
allowLinks	boolean	`true` `false` Valid only for `string` data type	Whether a hyperlink can be specified for a column value
linkTarget	string	`_blank` `_self` Valid only if `allowLinks=true`	`_blank` opens link in a new window, `_self` opens link in the same window
editLines	int	Valid only for `string` data type	The number of lines when editing a column value (default=1)
peopleScope	string	`GLOBAL` `SUB_SCOPE` Valid only for `person` data type	Whether valid users are all users in directory or members of the portal that contains the list
displayWidth	int	—	Display width of column in pixels
hint	string	—	Hint displayed to help user when entering column value

^Footnote 17

Denotes required element

^Footnote 18

Denotes required element

For example:

<metaColumn>
   <name>Comments</name>
   <dataType>richtext</dataType>
</metaColumn>

Request headers: Content-Type = application/xml | application/json, [Accept = application/xml | application/json]
Response status: 200 [OK]
Response body: <metaColumn>

Method (column): DELETE

Use this method to delete a list column.

Resource URI, for example:

http://host:port/rest/api/spaces/vs1/lists/(/oracle/webcenter/list/scopedMD/
s355923f0_2f04_4fd0_83ad_f7dac2a7ceed/lists/ls_c9cecbc7_756b_417b_a35f_
fb03874979c0.xml)/columns/(lco_fe2b9856_32f3_449a_a277_
18dc7f6a779e)?utoken=FKld8lalI3QRdi8TgQkOCGEzxL5x_w**

Request body: none
Response status: 204 [No Content]
Response body: none

C.19.4.6.3 Resource Types Linked to from column

Table C-78 lists the resource types that the client can link to from the column resource.

Table C-78 Resource Types Linked to from column

rel	resourceType
self	`urn:oracle:webcenter:space:list:column`

C.20 Using the Activity Graph REST APIs

WebCenter Portal provides REST APIs to support the activity graph. Use the activity graph REST APIs to create your own interface for providing recommendations for connections, portals, and items.

This section describes the REST APIs associated with the activity graph. It includes the following topics:

For an introduction to the REST APIs, see Introduction to the WebCenter Portal REST APIs.

C.20.1 Activity Graph Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For the activity graph, there are two entry points: one for recommendations and one for items. To find the entry points for the activity graph, find the link element with one of the following resourceTypes:

urn:oracle:webcenter:activitygraph:recommendations
urn:oracle:webcenter:activitygraph:items

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with the activity graph.

For more information about the Resource Index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.20.2 Activity Graph Resource Type Taxonomy

When the client has identified the entry point to use, it can then navigate through the resource type taxonomy to perform the required operations.

The taxonomy for the activity graph is:

urn:oracle:webcenter:activitygraph:recommendations
   urn:oracle:webcenter:activitygraph:recommendations:recommendation
urn:oracle:webcenter:activitygraph:items
   urn:oracle:webcenter:activitygraph:items:item

C.20.3 Security Considerations

For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.20.4 Activity Graph Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following topics:

C.20.4.1 urn:oracle:webcenter:activitygraph:recommendations

Use this resource to identify the URI to use to retrieve (GET) recommended connections, portals, or items based on their similarity to the specified object. The response from a GET operation includes each object in the requested list, and each object includes links used to operate on that object.

Nodes in the activity graph are identified by a combination of node class URN and object URN.

For example, to identify the user, monty, you can specify:

classURN=WC.user
objectURN=monty

The nodes provided out of the box are all WebCenter Portal resources (users, documents, portals, and so on) and so have WebCenter Portal service and resource IDs. The activity graph REST APIs provide another way for you to identify these out of the box nodes using the serviceId and objectURN (which contains the resource ID).

For example, to identify the user, monty, you can specify:

serviceId=oracle.webcenter.people
objectURN=monty

If a service's objects are further classified by resource type, for example, the Documents tool, you must also specify the resource type.

For example, to identify a particular document, you can specify:

serviceId=oracle.webcenter.doclib
resourceType=document
objectURN=document1

Any new node classes that are created (that is, non-native WebCenter Portal objects) should be identified using node class and object URNs.

C.20.4.1.1 Navigation Paths to recommendations

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   recommendations

C.20.4.1.2 Supported Methods for recommendations

The following methods are supported by this resource:

GET
- request - Parameters: startIndex, itemsPerPage, utoken
  
  For information about these common parameters, see Common Request Query Parameters.
  
  The following additional parameters are available:
  - classURN—The node class URN that identifies the type of the object for which you are requesting recommendations. For example WC.user, WC.group-document.
  - objectURN—The object URN that provides a unique identifier for the object for which you are requesting recommendations. For example monty, 1000.
  - recipe—A semicolon-separated list of similarity URNs and optional associated weights (indicated by a colon) that is used to determine which objects to recommend. For example, gs-edit:10;gs-all:1
  - classURNRestrictions—A comma-separated list of types of objects, identified by node class URN, to exclude from the recommendations
  - excludeObjectActions—A comma-separated list of actions, identified by action URN, used to exclude objects from the recommendations if the current user has performed that action on the object. For example, if the client is retrieving recommended portals, then the gs-edit action could be specified to exclude portals that the current user has edited (since the user already knows about those portals).
  - serviceId—The WebCenter Portal service ID that identifies the type of object for which you are requesting recommendations (you can use this instead of classURN for out of the box objects).
  - resourceType—The WebCenter Portal resource type of the object for which you are requesting recommendations, used in combination with serviceId if necessary.
  - userCredentialClassURN—The node class URN of the user exercising the REST API. The default value is WC.user. If you are integrating the activity graph engine with another application, this may need to be a different node class.
- response - body: 0 or more recommendations

For more information, see Templates.

C.20.4.1.3 Resource Types Linked to from recommendations

Table C-79 lists the resource types that the client can link to from this resource.

Table C-79 Related Resource Types for recommendations

rel	resourceType
self	urn:oracle:webcenter:activitygraph:recommendations

C.20.4.2 urn:oracle:webcenter:activitygraph:recommendations:recommendation

The recommendation response contains the recommended objects and the URIs for use in accessing those objects.

C.20.4.2.1 Navigation Paths to recommendation

This section shows how the client can navigate through the hypermedia to access the recommendation resource:

resourceIndex
   recommendations
      recommendation

C.20.4.2.2 Read-only Elements for recommendation

Table C-80 lists the read-only elements for the recommendations resource.

Table C-80 Read-only Elements for recommendation

Element	Type	Description
`score`	Float	The overall score of this recommendation relative to the other recommendations in the list. This is the weighted sum of the component scores associated with each of the similarity URNs that comprise the recipe and is a floating point number between 0 and 1.
`item`	urn:oracle:webcenter:activitygraph:items:item	The recommended user, item, or portal.
`componentScores`	A list of `componentScore` elements	A list of the component scores associated with the different similarity URNs in the recipe for the recommendation. A component score may have a reason and a link that can be used to retrieve the common items with which the user and the recommended object have interacted.

C.20.4.3 urn:oracle:webcenter:activitygraph:items

Use this resource to identify the URI to use to retrieve (GET) objects that the source object and recommended object have in common. You can use this to determine the reasons why a particular object was recommended. The response from a GET operation includes each item in this collection of items, and each item includes links used to operate on that item.

C.20.4.3.1 Navigation Paths to items

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   items

C.20.4.3.2 Supported Methods for items

The following methods are supported by this resource:

GET
- request - Parameters: startIndex, itemsPerPage, utoken
  
  For information about these common parameters, see Common Request Query Parameters.
  
  The following additional parameters are available:
  - similarityURN—The URN of the similarity calculation to be used determine which objects are similar to the recommended object. For example item-tag, gs-edit, user-connect
  - srcClassURN—The node class URN that identifies the type of the object that was used to request the recommendations. For example WC.user, WC.group-document.
  - srcObjectURN—The URN of the object that was used to request the recommendations. For example monty, 1000.
  - trgClassURN—The node class URN that identifies the type of the recommended object
  - trgObjectURN—The object URN that provides a unique identifier for the recommended object
  - userCredentialClassURN—The node class URN of the user exercising the REST API. The default value is WC.user. If you are integrating the activity graph engine with another application, this may need to be a different node class.
- response - body: 1 or more items

For more information, see Templates.

C.20.4.3.3 Resource Types Linked to from items

Table C-81 lists the resource types that the client can link to from this resource.

Table C-81 Related Resource Types for items

rel	resourceType
self	urn:oracle:webcenter:activitygraph:items

C.20.4.4 urn:oracle:webcenter:activitygraph:items:item

Use this resource type to identify the URI to use to update (PUT) a recommendation to indicate user interest in the recommended object.

C.20.4.4.1 Navigation Paths to item

This section shows how the client can navigate through the hypermedia to access the item resource:

resourceIndex
   recommendations
      recommendation
         item
resourceIndex
   items
      item

C.20.4.4.2 Supported Methods for item

The following method is supported by this resource type:

PUT
- Request—Body: item
- Response—Body: item

C.20.4.4.3 Writable Elements for item

Table C-82 lists the writable elements for this resource type.

Table C-82 Writable Elements for item

Element

Type

Required

Constraints

Description

status

String

Yes

interested

not interested

Whether the user is interested in the object

C.20.4.4.4 Read-only Elements for item

Table C-83 lists the read-only elements for this resource type. Not all of these elements are available for all objects.

Table C-83 Read-only Elements for item

Element	Type	Description
classURN	String	Node class of the object
objectURN	String	Identifier for the object
name	String	Name of the object
description	String	Description of the object
modified	Date	Date on which the object was last updated
modifiedByUser	PersonReference	User information about the user who last updated the object, including GUID, ID, display name, and a link to the profile icon
author	PersonReference	User information about the user who created the object, including GUID, ID, display name, and a link to the profile icon

C.20.4.4.5 Resource Types Linked to from item

Table C-84 lists the resource types that the client can link to from this resource.

Table C-84 Related Resource Types for item

rel	resourceType
self	urn:oracle:webcenter:activitygraph:items:item
via	`resourceType` of the underlying object

C.21 Using the Search REST APIs

WebCenter Portal provides REST APIs that let you build a customized search user interface. With Oracle SES 11.2.2.2, you can use the search REST APIs to read (GET) searches and facets. Facets are returned with search results and can be used to filter the results. You can specify keywords and the scope of the search; for example, suppose a search for the term 'webcenter' produces thousands of results. A user could use facets (such as author or last modified date) in the URL to get the results for particular facet values, like author=Karen and last-modified-date=this week.

This section includes the following topics:

For an introduction to the REST APIs, see Introduction to the WebCenter Portal REST APIs.

C.21.1 Search Entry Point

Each REST service has a link element within the resource index that provides the entry point for that service. To find the entry point for search, find the link element with a resourceType of:

urn:oracle:webcenter:searchcollection

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with search.

See Also:

There are two entries for search in the resource index:

urn:oracle:webcenter:searchcollection (This requires WebCenter Portal to be configured with Oracle SES 11.2.2.2.)
urn:oracle:webcenter:searchresults (This requires WebCenter Portal to be configured with Oracle SES--any supported version.)

This topic describes only urn:oracle:webcenter:searchcollection. For detailed information about urn:oracle:webcenter:searchresults, see:

http://docs.oracle.com/cd/E28280_01/webcenter.1111/e10148/jpsdg_search.htm.

For more information about the resource index, see Using the Resource Index.

For more information about resource types, see Resource Type.

C.21.2 Search Resource Type Taxonomy

The taxonomy for the search is:

urn:oracle:webcenter:searchcollection
   urn:oracle:webcenter:searchcollection:results

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

Collection resources in the search resources support pagination (startIndex and itemsPerPage). The entry point returns all the results in searchcollection element. Query various components by specifying appropriate values in dataType argument.

Support for searchTerms, data, and dataType where dataType has one or more of the following values:

resultCount - number of results satisfying the query
results - actual results
facetCount - number of facets for the query result
facets - facets for the current results

Specify more than one dataType with comma separated values. For example:

http://host:port//rest/api/searchcollection?&dataType=results,facets
&facetParams=author:weblogic&utoken=FDX7xKPzzrnsbWRHNP-b-iUoWiJ4_w\*\\\\\\\\*

C.21.2.1 Navigation Paths to results

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   searchcollection

resourceindex
   spaces
      spaces:resourceindex
         spaces:searchcollection

C.21.2.2 Supported Methods for results

The following methods are supported by this resource:

GET
- request - body: none, Parameters: q, dataType, startIndex (pagination), itemsPerPage (pagination), data, facetParams
- response - body: search results, and optionally facets

where:

q={queryString}

Searches may be specified using the following format:
```
[[field1:[operand]][:]value1[;field2:operand:value2]]
```
Where multiple clauses are joined by an implicit AND and are syntactically separated by the ";" semicolon. Square brackets [] denote optional values. Each clause can be a keyword simple string with no ":" colon separator.

The query string does not support anything other than a query keyword.
dataType is the type of results

For example, if you want only results, then dataType=results (or left empty). To include facets in the results, then dataType=results,facets.
data is parameters for custom attributes

For example:
```
data=numberofreplies,wc_tagsWords
```
facetParams is parameters for facet refinement

Default set is Service ID, scope GUID, Tags, Author, Last Modified Date, Mimetype.

For example, to refine by people, set the facet Service ID only to oracle.webcenter.people:
```
facetParams=Service%20ID:oracle.webcenter.people
```

Note:

If you want to use the facetParams parameter, then the dataType parameter must include facets.

Example: Search REST Commands

http://examplehost:8888/rest/api/searchcollection?q=document&utoken={utoken}

http://examplehost:8888/rest/api/searchcollection?q={keyword}
&data=dDocName,dOriginalName&dataType=results,facets
&facetParams=Service%20ID:oracle.webcenter.people

For more information, see Templates.

Table C-85 Writable Elements for results

Element	Type	Description
`author`	String	Any user who has written to the result
`resourceId`	String	Unique identifier
`serviceId`	String	Service ID of the result; for example, oracle.webcenter.doclib
`title`	String	Title of result
`description`	String	Description of result
`modified`	Date	Last modified date
`size`	Number	Size of result
`docid`	String	Document identifier
`created`	Date	Original author of result
`icon`	String	Icon for result type
`url`	String	URL of result
`mimetype`	String	Mimetype of result
`guid`	String	GUID value of result
`scope`	String	GUID value of the portal
`scopename`	String	Portal name
`resourceType`	String	Type of result
`language`	String	Language of result
`snippet`	String	Snippet of result
`modifier`	String	Modifier of result
`customattributes`	any	List of any custom attributes specified in data

C.21.2.3 Resource Types Linked to From results

Table C-86 lists the resource types that the client can link to from this resource.

Table C-86 Related Resource Types for search

rel	resourceType
self

C.21.3 Security Considerations

Authentication is required before using search REST API methods.

For general security considerations, see Security Considerations for WebCenter Portal REST APIs.

C.21.4 Search Resource Types

This section provides information about each resource type. It includes the following topics:

C.21.4.1 urn:oracle:webcenter:searchcollection:links

Use this resource type for template links and pagination links.

C.21.4.2 urn:oracle:webcenter:searchcollection:results

Use this resource type to identify the URI to use to read (GET) a query containing keywords and facets.

The request is represented by the URL and the response is a list of search results, each with metadata to help the end user choose an item to drill down, as well as cross links to the owning REST services, if available. If the owning REST service is unavailable, then an HREF link is provided.

The response XML can be paginated with standard URL parameters, and appropriate previous and next links provided along with a general template (with the query prepopulated) for the consuming application to do its own custom pagination.

C.21.4.3 urn:oracle:webcenter:searchcollection:facets

Use this resource type to identify the URI to use to read (GET) a query containing facets. Facets are returned with the query results and can be used to filter the results. Users can use these facets in the URL to get the results for particular facet values, like author=weblogic and last-modified-date=this week.

The request is represented by the URL and the response is a list of facets, each with metadata to help the end user choose an item to drill down, as well as cross links to the owning REST services, if available. If the owning REST service is unavailable, then an HREF link is provided.

Element	Type	Required	Constraints	Description
name^Foot 10	string	Yes	1 or more characters	Name of this list
description	string	No	none	Description of this list

Element	Type	Constraints	Description
columns.column.id^Foot 11	string	—	Column ID
columns.column.value^Foot 12	string	Valid value for column data type	Column value

Element	Type	Constraints	Description
columns.column.id^Foot 13	string	—	Column ID
columns.column.value^Foot 14	string	valid value for column data type	Column value