REST API for Documents

You can use the Oracle Cloud REST API for Documents to create client applications that interact with folders and files stored on an Oracle Content and Experience server.

Version History

The REST API for Documents identifies its version by including a version number in the URI in the form of /x.y/ folders, such as /1.2/.

To use a particular implementation of the API, you must reference that version in the URI. For more information about referencing a particular version of the API, see Service Call URI and Version.

Version 1.0

Version 1.0 provides basic folder, file, resource, and version identification services and their methods.

Version 1.1

Version 1.1 adds the following major services and their methods:

  • Metadata Collection Resource

    A metadata collection is a simple way of managing custom metadata fields that you can then use to store and retrieve metadata values for individual folders and files.

  • Users Resource

    Service requests and responses that referenced the simple user string in version 1.0 now reference the user object.

    These search requests were added:

    • User email search

    • Fulltext search for a folder in the user’s home directory

    • Fulltext search for a file in the user’s home directory

  • Applinks Resource

  • Publiclinks Resource

  • Shares Resource

  • Collections Resource

The Files Resource service includes these additional calls:

  • Reserve File (POST)

  • Unreserve File (POST)

  • Get File Thumbnail (GET)

  • Get File Rendition Page Count (GET)

  • Generate File Renditions (POST)

  • Get File Page Rendition (GET)

The Files Resource also supports additional mimeType, reservedBy, and reservationTime elements.

Requests were added to the Metadata Collection Resource for these tasks:

  • Enable or disable a metadata collection

  • Enable or disable fields in a metadata collection

  • Get a metadata collection definition

  • Get user metadata

  • Get share metadata

  • Get application links metadata

  • Get public links metadata

  • Get assigned metadata collections to a file showing enabled or disabled field status

  • Get assigned metadata collections to a folder showing enabled or disabled field status

  • Delete a metadata collection

The Folders Resource includes additional createdby and modifiedby elements in responses.

The Applinks Resource supports an additional userLocale element.

The Upload File Version (POST) method no longer requires the use of parentID in the multipart request.

An errorKey field was added to responses.

The catalog category was renamed metadata-catalog. The catalog name will continue to be supported as an alias for metadata-catalog.

Version 1.1 of the REST API for Content Management provides a Web Application Definition Language (WADL) definition file. Oracle JDeveloper uses this file to interface with the API.

The REST API for Content Management 1.1 is the legacy version of the REST API for Documents.

Version 1.2

Version 1.2 includes all the functionality of Version 1.1 and adds the following major services and their methods:

  • Sites Resource, for creating a site from an existing site.

  • Templates Resource, for creating a site from a template.

The REST API for Documents, Version 1.2, is the ongoing version of the REST API for Documents.

REST API Features for Documents

Features of the REST API for Documents apply to all services.

The following topics describe these common features:

REST Overview

REST, or Representational State Transfer, uses basic methods such as GET, POST, PUT, and DELETE over a standard protocol, such as HTTPS, to submit requests from a client application to operate on objects stored on a server.

A request is in the form of a uniform resource identifier (URI) that identifies the resource, such as a file or folder, on which to operate and includes any parameters necessary for the operation. The resource itself is represented by a globally unique identifier (GUID).

Each request from the client to a server contains all of the information necessary to understand the request and does not rely on the server to store information about the individual request or about any relationship between requests. Session state is stored (cached) entirely on the client.

You can use the REST API for Documents to create client applications to interact with folders and files stored on an Oracle Content and Experience server.

For information about the hierarchy of the REST API objects and methods, see REST API for Documents.

Service Call URI and Version

A service call includes an HTTPS method, such as POST, GET, PUT, or DELETE, and a resource identified by a Uniform Resource Identifier (URI).

The URI is in this format:

https://{host}[:port]/serviceid/api/version/resourcePath

Note:

HTTPS is supported. HTTP is not supported.

The REST API identifies its version by including a version number in the URI in the form of /x.y/ folders, where x is incremented for subtractive changes or modifications to existing functionality and y is incremented when new features are added. For example:

https://www.example.com/documents/api/1.1

The Catalog Resource lists the currently supported API versions for the instance.

Service Request

A REST API supports a direct URL and JSON data format for service requests.

REST API for Documents includes examples of service requests.

URL Parameters

Unless otherwise noted, you can include service request parameters directly in the URL. The following example of the Query User (GET) service call includes the required info parameter in the URL itself:

https://www.example.com/documents/api/1.1/users/items?info=smith

JSON Parameters

Unless otherwise noted, you can submit service request parameters in JSON format. The following example shows a simple service call and the info parameter in a JSON-formatted request:

https://www.example.com/documents/api/1.1/users/items
{
    "info": "smith"
}

Multipart Requests

Some service calls require a multipart request. For these types of requests, you must include the parameters in a JSON-formatted request. For an example of a multipart request, see the Examples tab of "Upload File Version" under "Files" in REST API for Documents.

Header Parameters

Some types of information, such as authentication information, are passed in the request header rather than in the body of the request. This is also true for service requests that use an application link (applink). An applink grants access to a particular file or folder resource for a particular user. The applink enables you to programmatically carry out other operations on that resource on behalf of the associated user for a period of time. A service call that uses an applink includes the applink identifier and its access token in the header.

For an example, see the applink header parameters on the Examples tab of "Refresh Applink Token" under "Applinks" in REST API for Documents.

For more information about applinks, see Applinks Resource.

Service Response

The REST API supports the JSON and XML data formats for service responses.

The Download File (GET) service call returns the contents of a specified file.

You can specify the data format for the response using the Accept HTTP header. If you don't specify a data format, JSON is used by default for the response. For example:

Accept: application/xml

The service response includes a general status code and, in some cases, a fault response body to help diagnose the issue. This information is returned in the specified JSON or XML format.

Requests that do not reach a valid API endpoint, such as improperly formed requests, may return a response in a format other than JSON or XML. These types of errors typically occur during code development, not with properly tested and deployed applications.

Examples of service responses are included with the API descriptions in REST API for Documents.

Security

Oracle Content and Experience uses a multilayered approach to protect your system and content.

Security Feature Description Who Manages It and Where
User accounts You need an account with a user name and password to access Oracle Content and Experience. Identity domain administrators manage user accounts in the Infrastructure Classic Console.
User roles Each user is assigned one or more roles to control what functionality and areas of the web user interface they can access. Identity domain administrators or service administrators assign user roles in the Infrastructure Classic Console.
Groups Groups make it easy to grant multiple users access to folders, conversations, and content types. By adding someone to a group or removing them from a group, you can quickly update the permissions to all the items that group has access to. Service administrators should create high-level organizational groups. Users can create additional groups as necessary.
Mobile device passcodes When accessing files on a mobile device, you can set a passcode to provide additional security. The passcode is a four-digit number that is set and managed on your device. It's used in addition to your user name and password. Users manage their passcodes on their mobile devices.
Revoke authorization for a mobile device If a user loses their device or it’s taken, they should remove that device's authorization to access the service. The next time someone tries to activate the app on the device, the account is signed out and all local content stored on the device for that account is deleted. Users can revoke a device from the web client.
Single Sign-On (SSO) If Federated Single Sign-On (SSO) is currently available for your Oracle Content and Experience Cloud environment, you can enable it to customize sign-in procedures. When Single Sign-On (SSO) is enabled, users can sign in to one domain using corporate security credentials and access another domain without signing in again. For example, perhaps you are an administrator for your company which has two Oracle Cloud Services and you must provision these services to your company’s organization, roles, and users. Your company may also have on-premise applications and cloud services from other vendors. It’s important that communication between these services and applications is done in a secure fashion. With SSO, users can sign in to all of them using the same set of credentials that are managed by using your identity domain system. Account administrators can enable single sign-on (SSO) in the Infrastructure Classic Console.
File encryption Files are protected using Secure Sockets Layer (SSL) technology. Files are encrypted while they're uploaded (in transit) and when they’re stored (at rest) in the cloud. Files at rest that are stored using the Oracle Storage Cloud service are encrypted using a 256–bit RSA encryption algorithm. That prevents unauthorized use of the files.

Any files downloaded to a mobile device are also encrypted. You can't access those files outside of the Oracle Content and Experience app unless you specifically download the file for use on the device.

File encryption is handled automatically by Oracle Content and Experience.
File type and size restrictions You can specify which types of files can be uploaded and restrict the size of uploaded files. Service administrators configure file type and size restrictions through the Oracle Content and Experience Administration interface.
Virus scanning When you upload files to the cloud, they can be checked by a virus scanner. Any files found to be infected are quarantined in the Trash bin and a special icon marks the file as infected. Service administrators configure virus scan settings through the Oracle Content and Experience Administration interface.
File access control You have total control over who can access your files. You can add co-workers as members of a folder. The added users are granted default access rights, but folder managers can also change those rights.

In addition to sharing folders, you can also share files using links. If you send a link to a member of a folder, the member can sign in and use the file in the service. If you send the link to a non-member, that person is restricted from seeing other files in the folder.

Service administrators set the default role for new folder members and set default link behavior.

Users control access when they share content.

Conversation encryption Conversations at rest are stored using the Oracle Storage Cloud service and are encrypted using a 256–bit RSA encryption algorithm. That prevents unauthorized access to conversation content. Conversation encryption is handled automatically by Oracle Content and Experience.
Site creation and sharing restrictions You can specify who can create, share, and use sites functionality, which lets users design, build, publish, and manage websites that are hosted in Oracle Cloud. Service administrators configure sites settings through the Oracle Content and Experience Administration interface.
Site security When you publish a site and make it available online, it’s publicly available to anyone. However, you can change the security settings for the site to require users to sign in. You can also require that users have a specific role assigned to them. Site owners and managers control the security for individual sites.
Site sharing With site sharing, you specify individual users who can access your unpublished (offline) site and allow them to view, modify, or manage the site based on the permission you give them. Site owners and managers control the security for individual sites.
Site component sharing Some components provide access to shared resources such as folders, files, or conversations. Component sharing considers both site security (who can view the published site) and resource sharing (who can view and work with folders, files, and conversations). Site component sharing is handled automatically by Oracle Content and Experience based on site and resource security.
Cross-Origin Resource Sharing (CORS) Cross-Origin Resource Sharing (CORS) allows a web page to make requests such as XMLLHttpRequest to another domain. If you have a browser application that integrates with Oracle Content and Experience Cloud but is hosted in a different domain, add the browser application domain to Oracle Content and Experience Cloud’s CORS origins list. Service administrators configure CORS through the Oracle Content and Experience Administration interface.
Proxy service Oracle Content and Experience Cloud includes a proxy service, so that you can use REST services which have Cross-Origin Resource Sharing (CORS) limitations or require service account credentials. The proxy service is a reverse proxy server. It provides a URL to which web browsers connect. The proxy service then acts as an intermediary between the web browser and a remote REST service (or endpoint). The proxy service explicitly adds CORS support to all endpoints and can optionally insert service account credentials to requests coming from web browsers. Service administrators configure the proxy service through the Oracle Content and Experience Administration Integrations interface.
Embedded content whitelist You can display content from Oracle Content and Experience within other domains. For example, you might embed the Oracle Content and Experience web user interface into your own web applications to access folder and document management features inside your application. The embedded content appears only if embedded content is enabled and the domain is added to allowed domains whitelist. Service administrators configure embedded content settings through the Oracle Content and Experience Administration interface.

Sort Order

For services that return items in a folder, you can use the orderby parameter to order the results based on a specified field name and sort order (ascending or descending).

For an example of the orderby parameter in use, see Examples in the description of "Get Home Folder Contents" under "Folders" in REST API for Documents.

Pagination

Pagination capabilities are supported by default on all GET operations that have a response payload of XV1*ListInfo (for example, XV1ConversationListInfo), unless otherwise specified.

You can use offset and count in the query argument, where the default values are 0 and 20 respectively. For example:

https://<host:[<port>]/osn/social/api/conversations/<conversationID>/messages?offset=0&count=25

This request gets the first 25 messages, returning them with the newest message first. You can send additional requests to get incrementally older posts in the Conversation.

Links Identification

All service calls support the links=yes parameter, which returns link data that identifies the call itself and its relationship to other services.

The links parameter provides compliance with the HATEOAS (HTML as the Engine of Application State) standard, which uses valid HTML links returned by the server to identify the current resource and to navigate from one resource to another.

Relationships

A service call typically returns a number of links, each with a relationship type that identifies how the link is related to the associated call. The following table describes the most common relationship types.

Link Type Description

Self

Identifies the current service call.

Canonical

Identifies the preferred version of a resource call.

Child

For hierarchical resources, such as folders, this link identifies the call to access the child item or items of the resource identified in the current service call.

Parent

For hierarchical resources, such as folders, this link identifies the call to access the parent item of the resource identified in the current service call.

Prev

For service calls that include multiple pages of response data, this link identifies the call to access the previous page.

Next

For service calls that include multiple pages of response data, this link identifies the call to access the next page.

The link information returned for resource metadata includes other types of relationships, including ones that identify the type of service, such as copy, for each of the services supported for the resource. For more information, see Metadata Collection Resource.

Example

This example shows the links portion (only) for the home folder in the response to the following service call:

GET https://www.example.com/documents/api/1.1/folders/self/items?links=yes&limit=2&offset=1

The call requests a list of all the items in the home folder. Note that the call includes the links parameter and pagination parameters to help illustrate the available link relationships. Also note that, because the folder is the home folder, there is no link to represent the parent folder in the response.

"links": [
     {
          "rel": "self",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items?links=yes&limit=2&offset=1"
     },
     {
          "rel": "canonical",
          "href": "https://www.example.com/documents/api/1.1/folders/self"
     },
     {
          "rel": "children",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items"
     },
     {
          "rel": "prev",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items?offset=0&limit=2"
     },
     {          "rel": "next",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items?offset=3&limit=2"     }
],

HTTP Methods

The REST API for Documents supports the following standard HTTP methods.

Method Description

GET

Request information from the specified resource.

POST

Create a new instance of a resource.

PUT

Update an existing resource.

DELETE

Delete a resource.

HTTP Status Codes

A REST action returns a general status code.

For descriptions of the HTTP status codes that the REST API for Documents provides, see "Status Codes" under "Get Started" in REST API for Documents.

Error Codes

Some status codes are accompanied by a fault response body to help you diagnose the issue.

The following table describes general error codes returned by the errorCode field in the fault response body for an action. The errorMessage field in the response provides a more detailed description of the error.

Error Code Description

0

The action was successful.

-1

General failure. This code is returned when a more specific status code is not available.

-16

A folder or file with the specified name or ID does not exist in the specified location. This is typically returned as an HTTP 404 response code.

-17

A folder or file with the same name already exists in the target location.

-20

The user does not have sufficient privileges to perform the requested operation. This is typically returned as an HTTP 403 response code.

-26

The link is invalid or expired. This is typically returned as an HTTP 400 response code.

The following example shows the error code and message portion of a response:

{
    "errorCode": "-16",
    "errorMessage": "Security validation failed. 'FABCDEFGHIJKLMNOPQRSTUVWT0000000000100000001' does not exist. The error was caused by an internally generated issue. The error has been logged."
}

Applinks Resource

Use the Applinks resource (applinks) to request access to a folder or file for a specified user and role.

To create an applink, the requester must have admin privileges for the folder or file. That is, the requester must be the owner or have the manager role.

You can grant the specified user any standard role except the manager or owner role.

  • Viewer: Viewers can look at files and folders but can't change things.

  • Downloader: Downloaders can also download files and save them to their own computers.

  • Contributor: Contributors can also modify files, update files, upload new files, and delete files.

For an example of an applink definition, see Examples in the description of "Create File Applink" under "Applinks" in REST API for Documents.

Applink Encryption

All necessary resource object, user, and role information is encrypted and stored in the elements identified in the following table. These elements are returned with the applink response and are used to programmatically carry out other operations on behalf of the associated user for a defined period of time.

Service calls using an applink must include the associated appLinkID and accessToken values in the request header.

Parameter Description

appLinkID

This element uniquely identifies the resource.

accessToken

This element provides access to the resource and expires after 15 minutes. You can refresh the access token any number of times within the time period defined by the refresh token (24 hours).

refreshToken

This element enables you to request a new access token when the current access token expires. The refresh token expires after 24 hours.

Locales for the userLocale Applink Parameter

The following table lists locale codes and the locales they represent for the userLocale applink parameter.

Locale Code Locale

cs

Czech

da

Danish

de

German

el

Greek

en-CA

English-CA

en-GB

English-UK

en-US

English-US

es

Spanish

fi

Finnish

fr

French

fr-CA

French-Canadian

hu

Hungarian

it

Italian

ja

Japanese

ko

Korean

nl

Dutch

nb

Norwegian_Bokmål

no

Norwegian

pl

Polish

pt

Portuguese-Portugal

pt-BR

Portuguese-Brazilian

ru

Russian

sk

Slovak

sv

Swedish

th

Thai

tr

Turkish

ro

Romanian

zh-CN

Chinese-Simplified

zh-TW

Chinese-Traditional

Applink Events

The Applinks resource supports the AppLinkReady event.

Event Description

AppLinkReady

Rather than send the required token data in a URL, which would make the tokens publicly visible and store them in various caches, this message is sent from an HTML inline frame (iframe tag) that contains the embedded user interface, to notify the parent window that the inline frame is ready to receive data from the Oracle Content and Experience server.

Message Handler Example

To pass the necessary keys (the short-term dAppLinkAccessToken and the long-term dAppLinkRefreshToken) into the inline frame without exposing them in a URL, use the AppLinkReady event. The basic steps follow:

  1. The inline frame that contains the embedded user interface uses a URL without keys to make the initial call to the Documents Cloud server.

  2. The server downloads JavaScript to the inline frame, which posts the AppLinkReady message to the parent window.

  3. The parent window posts data to the inline frame that contains the keys.

  4. The inline frame sends another URL to the Documents Cloud server with the short-term key in the header (not in the URL).

The following example illustrates a simple message handler. The createAppLink function referenced in the example is not shown but is assumed to return the necessary applink resource data:

$( document ).ready(function() {
	var id = "<Folder or File ID>";
	var role = "contributor";
	var assignedUser = "<User ID>";
	// createAppLink function not shown but assumed to return appLink resource data obtained 
	//    from Create Folder Applink or Create File Applink service
	var appLink  = createAppLink(id, role, assignedUser);
  	function OnMessage (evt) {          
		if (evt.data.message === 'appLinkReady') {
			
			var iframe= $('#applink_iframe')[0];
			var iframewindow= iframe.contentWindow ? iframe.contentWindow : iframe.contentDocument.defaultView;

			var msg = {
				message: 'setAppLinkTokens',
				appLinkRefreshToken:appLink.refreshToken,
				appLinkAccessToken:appLink.accessToken,
				appLinkRoleName:role,
				embedPreview: true
			}
			
			iframewindow.postMessage(msg, '*’);
 		}
	};
	window.addEventListener && window.addEventListener('message', OnMessage, false);
});

Applinks APIs

For REST endpoints and API descriptions, see "Applinks" in REST API for Documents.

Catalog Resource

Use the Catalog resource (metadata-catalog) to get information about what resources are available for a particular version of the REST API.

This resource queries the API Catalog to retrieve information about API versions, application links, files, folders, collections, metadata, public links, shares, users, and configuration.

Catalog APIs

For REST endpoints and API descriptions, see "Catalog" in REST API for Documents.

Collections Resource

Use the Collections API for basic collection operations.

You can create and delete collections, add assets to collections, remove assets, and retrieve a list of collections.

Collections Endpoints

For Collections REST endpoints and API descriptions, see "Collections" in REST API for Documents.

Configuration Resource for Documents

The Configuration resource for documents provides information about the Collaboration and Content Delivery Network (CDN) configurations.

The Get Collaboration Configuration endpoint retrieves the client URL, cList URL, OAuth client URL, OAuth cList URL, REST URL, and Service URL.

The Get CDN Configuration endpoint retrieves the CDN URL and description.

For REST endpoints and API descriptions, see "Configuration" in REST API for Documents.

Files Resource

Use the Files resource (files) to manage files in a file system. A file is a uniquely identified item associated with a folder (or parent). The parameters of the resource definition describe a physical file object.

Most operations, such as copy, move, and delete, are performed using only the information in the file resource definition. Actions that upload a new file or a new file revision require a multipart request that also identifies the content of the physical file object.

For an example of a file definition, see the Examples tab in the description of "Get File Information" under "Files" in REST API for Documents.

Files Endpoints

For Files REST endpoints and API descriptions, see "Files" in REST API for Documents.

Folders Resource

Use the Folders resource (folders) to manage folders in a file system. A folder is a uniquely identified item associated with a "parent" folder and optionally with folder and file "child" items.

These parent and child relationships create a hierarchy similar to the familiar folder structure in a conventional file system.

For an example of a folder definition, see the "Examples" tab in the description of "Get Folder" under "Folders" in REST API for Documents.

Folders APIs

For REST endpoints and API descriptions, see "Folders" in REST API for Documents.

Metadata Collection Resource

Use the Metadata Collection resource (metadata) to manage folder and file metadata. A metadata collection is a simple way of managing custom metadata fields that you can then use to store and retrieve metadata values for individual folders and files.

Within a collection, you can create one or more fields. To assign values to the fields in a metadata collection, you must first assign the collection to a particular folder or file. You can assign a collection to one or more folders or files, and any folder or file can have one or more collections assigned to it.

With a collection, you can add or remove fields and manage the group of fields as a whole. When you assign a collection to a folder or file, you effectively add the fields to the metadata for the folder or file. The values you assign to the fields are stored and retrieved as part of the metadata for the folder or file itself.

Metadata Inheritance

Custom metadata fields that you create and manage in a collection follow the same rules of inheritance that standard metadata fields follow. Metadata fields assigned to a folder are available to all folders and files in the hierarchy beneath that folder. Similarly, the values you assign to those fields are inherited by all folders and files nested beneath that folder unless explicitly defined for a nested folder or file. Metadata values specified for a folder or file replace the inherited value for that folder and, by the same rules of inheritance, for any folders or files in the hierarchy nested beneath that folder.

Field References

When setting or removing field values within a collections, there are two ways to reference collections and fields.

You can reference the collection and field names independently. Field references on the same service call use the specified collection implicitly:

/metadata?collection={collection name}&{field name}={field value}[&{field name}={field value}]

Alternatively, you can specify the collection and field name with each field reference:

/metadata?{collection name}.{field name}={field value}[&{collection name}.{field name}={field value}]

Metadata Collection APIs

For REST endpoints and API descriptions, see "Metadata Collection" in REST API for Documents.

Publiclinks Resource

Use the Publiclinks resource (publiclinks) to request access to a folder or file for any user, whether the user has an account or not.

You can have multiple, named links for the same resource with different access roles, expiration dates, and so on. You can also edit some of the information for an existing public link.

For an example of a publiclinks definition, see the Examples tab in the definition of "Get Public Link" under "Publiclinks" in REST API for Documents.

Publiclinks APIs

For REST endpoints and API descriptions, see "Publiclinks" in REST API for Documents.

Shares Resource

Use the Shares resource (shares) to share a folder and its contents with a specified user.

For information about finding users, see “Get Users" or "Get User with Email Address" under "Users" in REST API for Documents.

When you share folders, you control the permissions each person has for the folder and its files by assigning a role to the person. The different roles determine what a person can do with a shared file.

  • Viewer: Viewers can look at files and folders but can't change things.

  • Downloader: Downloaders can also download files and save them to their own computers.

  • Contributor: Contributors can also modify files, update files, upload new files, and delete files.

  • Manager: Managers have all the privileges of the other roles and can add or remove other people as members.

Shares APIs

For REST endpoints and API descriptions, see "Shares" in REST API for Documents.

Sites Resource

Use the Sites resource (sites) to create an Oracle Content and Experience site from another site.

The Sites API provides basic site operations.

Sites APIs

For REST endpoints and API descriptions, see "Sites" in REST API for Documents.

Templates Resource

Use the Templates resource (templates) to create a site from a template.

The Templates API provides basic template operations.

Templates APIs

For REST endpoints and API descriptions, see "Templates" in REST API for Documents.

Users Resource

The Users resource (users) provides basic information about users to identify them for folder sharing and file sharing.

Users APIs

For REST endpoints and API descriptions, see "Users" in REST API for Documents.