28 Using Oracle WebCenter REST APIs

28.3.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 Section 28.5, "Navigating Hypermedia Using HTTP."

28.3.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

28.3.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

28.3.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 XML. For more information about CMIS REST APIs, see Oracle Fusion Middleware Content Management REST Service Developer's Guide.

28.3.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.

Example 28-7 shows a URI template including several request query parameters.

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

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

For example, using the template in Example 28-7, to see 10 list items 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 in Example 28-8.

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

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 in Example 28-9.

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

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 chapter 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
  

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

28.7.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.

28.7.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.

28.7.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

• 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.

28.7.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 valid values of thumbnail

28.8.1.1 Accessing the Resource Index

The first step is always to access the Resource Index (Example 28-10).

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 28-11).

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.

28.8.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 (Example 28-12).

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

GET /opaque-messageBoard-URI
 

The response provides information about all the messages on your message board (Example 28-13).

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

28.8.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 28-14).

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 28-15).

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" 
      } 
    ] 
  }
  ] 
}

28.8.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 28-16).

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 28-17).

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...

}

28.8.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 28-18).

DELETE opaque:message:URI

The response is simply a status code of 204 (Example 28-19).

204 NO CONTENT