Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Ensemble 10g Release 3 (10.3.0.1.0) E14115-02 |
|
![]() Previous |
![]() Next |
Oracle WebCenter Ensemble REST APIs provide the following functionality:
Allow remote web services to retrieve information about resources and pagelets from Oracle WebCenter Ensemble; for details, see Data Retrieval APIs.
Inject pagelets into non-proxied pages, allowing Oracle WebCenter Ensemble to act as a portlet provider for Oracle WebCenter Interaction, Oracle WebLogic Portal, or other third-party portals for details, see Pagelet Inject API.
REST stands for Representational State Transfer and is a simple way of providing APIs over HTTP. The basic principles of REST are:
API URLs point to the resource being used, rather than a generic method endpoint.
Requests use standard HTTP verbs for simplified CRUD methods. This is a read-only API and allows GET requests only.
Every request should return a full representation of the object retrieved (pagelet or resource).
Two REST APIs are available to retrieve data from Oracle WebCenter Ensemble:
Pagelet API: Allows remote applications to retrieve pagelet data from Oracle WebCenter Ensemble.
Resource API: Allows remote applications to retrieve resource data from Oracle WebCenter Ensemble.
The base URL for all requests is http://<Ensemble base URL>/api/v2/ensemble/
The following arguments are available:
Argument | Returns | Example: Pagelet API | Example: Resource API |
---|---|---|---|
None | All pagelets or resources. | http://myensemble.com/api/v2/ensemble/pagelets | http://myensemble.com/api/v2/ensemble/resources |
Library or Resource name | All pagelets within a specific library, or a specific resource. | http://myensemble.com/api/v2/ensemble/pagelet/samples/ | http://myensemble.com/api/v2/ensemble/resource/sampleresource/ |
name | The pagelet with the specified name. | http://myensemble.com/api/v2/ensemble/pagelets?name=samplepagelet | To retrieve a specific resource, use the syntax above. |
resultCount | List of all pagelets or resources, limited to the specified result count. | http://myensemble.com/api/v2/ensemble/pagelets?resultCount=3 | http://myensemble.com/api/v2/ensemble/resources?resultCount=3 |
id | A pagelet or resource with the specified id. | http://myensemble.com/api/v2/ensemble/pagelets?id=5 | http://myensemble.com/api/v2/ensemble/resources?id=5 |
owner | A list of resources associated with the specified user. | n/a | http://myensemble.com/api/v2/ensemble/resources?owner={35DE6AF8-ABB6-4e9b-B4E1-D1FC492F2BE8} |
externalurlprefix | A list of resources associated with the specified URL. | n/a | http://myensemble.com/api/v2/ensemble/resources?externalurlprefix=http://joesmith.amer.bea.com:80/login/ |
format | The format to use in the response (xml or json). Responses are returned in XML by default. | http://myensemble.com/api/v2/ensemble/pagelets?format=json | http://myensemble.com/api/v2/ensemble/resources?format=json |
For example, the http://myensemble.com/api/v2/ensemble/pagelets?id=5 request returns the following:
<ns2:Pagelet> <name>attributepagelet</name> <desc>This pagelet uses attributes.</desc> <id>5</id> <lastModified>2008-03-03T13:12:44.683-08:00</lastModified> <created>2008-03-03T13:12:44.683-08:00</created> <m_strLibraryName>samples</m_strLibraryName> <parent_resource_name>samples resource</parent_resource_name> <parent_resource_desc>This resource contains the standard sample pages.</parent_resource_desc> <parent_resource_id>8</parent_resource_id> <parent_resource_external_url_list>/samples/</parent_resource_external_url_list> - <parent_resource_external_url_list> https://daniilk-w2k3.devnet.plumtree.com:443/samples/ </parent_resource_external_url_list> - <m_strCodeSample> <pt:ensemble.inject pt:name="samples:attributepagelet" param1="0" param2=""> </pt:ensemble.inject> </m_strCodeSample> <m_bPublishDocs>true</m_bPublishDocs> <m_addInlineRefreshToAllUrls>false</m_addInlineRefreshToAllUrls> <m_refreshInterval>0</m_refreshInterval> <url_suffix>attributepagelet.html</url_suffix> <pagelet_external_url>/inject/v2/pagelet/attributepagelet/samples</pagelet_external_url> <parametersTransport>PAGELET_REALM</parametersTransport> <m_bAllowAll>true</m_bAllowAll> </ns2:Pagelet>
If the format is specified as JSON (http://myensemble.com/api/v2/ensemble/pagelets?id=5&format=json), the following response is returned:
{"ns2$Pagelet":{"@xmlns":{"ns2":"http:\/\/social.bea.com\/ensemble"},"name":{"name":"attributepagelet"},"desc":{"desc":"This pagelet uses attributes."},"id":{"id":"5"},"lastModified":{"lastModified":"2008-03-03T13:12:44.683-08:00"},"created":{"created":"2008-03-03T13:12:44.683-08:00"},"m_strLibraryName":{"m_strLibraryName":"samples"},"parent_resource_name":{"parent_resource_name":"samples resource"},"parent_resource_desc":{"parent_resource_desc":"This resource contains the standard sample pages."},"parent_resource_id":{"parent_resource_id":"8"},"parent_resource_external_url_list":[{"parent_resource_external_url_list":"\/samples\/"},{"parent_resource_external_url_list":"https:\/\/daniilk-w2k3.devnet.plumtree.com:443\/samples\/"}],"m_strCodeSample":{"m_strCodeSample":"<pt:ensemble.inject pt:name=\"samples:attributepagelet\"\nparam1=\"0\"\nparam2=\"\">\n\n<\/pt:ensemble.inject>"},"m_bPublishDocs":{"m_bPublishDocs":"true"},"m_addInlineRefreshToAllUrls":{"m_addInlineRefreshToAllUrls":"false"},"m_refreshInterval":{"m_refreshInterval":"0"},"url_suffix":{"url_suffix":"attributepagelet.html"},"pagelet_external_url":{"pagelet_external_url":"\/inject\/v2\/pagelet\/attributepagelet\/samples"},"parametersTransport":{"parametersTransport":"PAGELET_REALM"},"m_bAllowAll":{"m_bAllowAll":"true"}}}
By entering a proxy URL into the portal portlet source code, Oracle WebCenter Ensemble will load up the pagelet as a portlet. The proxy URL must use the following format:
http://host:port/inject/v2/pagelet/libraryname/pageletname?instanceid=55&content-type=html
where libraryname and pageletname refer to the library and pagelet configured in Oracle WebCenter Ensemble.
Note: When using the pagelet inject API as the URL for a Portlet Web Service in Oracle WebCenter Interaction, you must switch "pagelet" to "portlet" in the URL. For example, the above URL would become: http://host:port/inject/v2/portlet/libraryname/pageletname?instanceid=55&content-type=html |
The query string arguments to the above call define how the pagelet is to be returned. The following parameters are defined:
instanceid: Optional. The instance ID of the pagelet.
content-type: The return type. Three types are supported:
javascript: Returns injectable code.
html: Returns the pagelet markup with its associated PTPortlet object.
iframe: Returns an IFrame that points back to the inject api, filling the IFrame with the pagelet content, instead of directly inline with the page. The IFrame can be styled by providing a set of query string parameters.
Parameter | Description | Default |
---|---|---|
ifwidth | Sets the width of the IFrame; can be specified in percent '%' or pixels 'px', for example: ifwidth=500px. Can be set to 'auto' to automatically resize the IFrame to fit the content within. For details, see Using Automatic Resizing with IFrames. | 100% |
ifheight | Sets the height of the IFrame; can be specified in percent '%' or pixels 'px', for example: ifheight=500px. Can be set to 'auto' to automatically resize the IFrame to fit the content within. For details, see Using Automatic Resizing with IFrames. | No default |
ifborder | Sets the border of the IFrame. | 'none' |
ifalign | Sets the align rule within the IFrame, for example: ifalign=center. | No default |
ifdesc | Sets the description of the IFrame. | No default |
ifmarginheight | Sets the margin height; can be specified in percent '%' or pixels 'px', for example: ifmarginheight=500px. | No default |
ifmarginwidth | Sets the margin width; can be specified in percent '%' or pixels 'px', for example: ifmarginwidth=500px. | No default |
ifscrolling | Sets the scrollbars of the IFrame. Accepted values: yes/no/auto. | auto |
ifstyle | Sets the CSS style of the IFrame | No default |
ifclass | Sets the CSS class of the IFrame. | No default |
csapi: Sets whether the CSAPI will be included with the pagelet response (true or false). Including the CSAPI is optional, but the pagelet included in the response relies on the CSAPI libraries being present on the page where the pagelet is to be rendered. If csapi=false, then the CSAPI libraries must be included with the parent page (usually in the HEAD section).
onhtttperror:: When a pagelet request results in a 403, 404 or any other error code, Oracle WebCenter Ensemble can forward the error code and the error page itself to the browser for display to the user. The onhttperror parameter accepts the following values:
comment (default): Oracle WebCenter Ensemble will create an HTML comment in place of the failing pagelet (the failing pagelet will simply not be displayed).
inline: The pagelet error along with the server error page will be displayed inline where the pagelet would normally be shown on the page.
fullpage: The http error will consume the whole page. This mode is only available if Oracle WebCenter Ensemble controls the parent page.
For example, the following URL points to the linkpagelet in the samples library:
http://proxy:port/inject/v2/pagelet/samples/linkspagelet?content-type=iframe&csapi=true&ifheight=123px&ifclass=myclass
This URL should result in markup similar to the code below.
Note: The IFrame source points back to the inject API, but this time the content-type parameter is set to html. This feature adds an additional step in the pagelet retrieval. The csapi parameter is seet to true on the subsequent call to get the IFrame contents so that the required CSAPI content is included in the IFrame (if this was not the case, javascript resolve errors would be returned because the pagelet code cannot access any CSAPI script included outside the IFrame). |
<html> <head> </head> <body> <iframe frameborder="none" class="myclass" width="100%" height="123px" scrolling="auto" src="http://proxy:port/inject/v2/pagelet/samples/linkspagelet?asdg=asdfgas¶m=true&content-type=html&jswrap=false&csapi=true"> <html> <head> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsutil/LATEST/PTUtil.js" type="text/javascript"> </script> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsutil/LATEST/PTDateFormats.js" type="text/javascript"></script> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsxml/LATEST/PTXML.js" type="text/javascript"></script> <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsportlet/LATEST/PTPortletServices.js" type="text/javascript"></script> </head> <body> <div id="pt-pagelet-content-1" class="pagelet-container" style="display: inline;"> <span xmlns:pt="http://www.plumtree.com/xmlschemas/ptui/"> Pagelet links: <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/headpagelet1.html">The first pagelet</a> <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/headpagelet2.html">The second pagelet</a> <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/csapipagelet.html">The csapi pagelet</a> <br/> <a href="http://proxy:port/inject/RP_PID393219_I1/linkspagelet.html">This pagelet</a> <br/> </span> </div> </body> </html> </iframe> </body> </html>
The Oracle WebCenter Ensemble pagelet inject API can automatically resize the IFrame that encapsulates pagelet content. The resizing is done so that the IFrame stretches to fit the content within. To use this feature, the ifwidth and ifheight parameters must be set to 'auto' as shown in the example below:
http://proxy:port/inject/v2/pagelet/samples/linkspagelet?content-type=iframe&csapi=true&ifheight=auto&ifwidth=auto&ifclass=myclass
In addition, this feature relies on an external page on the same domain as the consumer page. This page is included into the pagelet IFrame as an internal hidden IFrame. This page collects the sizing information and passes it on to the parent consumer page. This page must be deployed in the same directory as the consumer page. An example is shown below.
<html> <head> <title>Resizing Page</title> <script type="text/javascript"> function onLoad() { var params = window.location.search.substring( 1 ).split( '&' ); var height; var width; var iframe; for( var i = 0, l = params.length; i < l; ++i ) { var parts = params[i].split( '=' ); switch( parts[0] ) { case 'height': height = parseInt( parts[1] ); break; case 'width': width = parseInt( parts[1] ); break; case 'iframe': iframe = parts[1]; break; } } window.top.updateIFrame( iframe, height, width ); } if (window.addEventListener) { window.addEventListener("load", onLoad, false) } else if (window.attachEvent) { window.detachEvent("onload", onLoad) window.attachEvent("onload", onLoad) } else { window.onload=onLoad } </script> </head> <body> </body> </html>