REST API for Conversations
You can use the Oracle Cloud REST API for Conversations to create and manage conversations in your cloud resources that enable real-time collaboration between individuals and teams and connect your business processes, enterprise applications, and content.
The REST API for Conversations uses the JSON data format and relies on a REST-based architectural style that provides a convenient and consistent approach to requesting and modifying data. The client specifies an action using an HTTP verb such as POST, GET, PUT, or DELETE. It specifies a resource using a unique URL in this format:
https://oracleContentInstance-identityName.network.dataCenter.oraclecloud.com/osn/social/api/v1/resource-path
-
oracleContentInstance
is the name you chose for your Oracle Content and Experience Cloud instance when it was provisioned. -
identityName
is the identity name you chose when you signed up with Oracle Public Cloud. -
network
is the name of your network. -
dataCenter
is the data center that Oracle Content and Experience Cloud is set up to use. -
resource-path
is the relative path that defines the resource.
The following topics provide overview information about developing with the REST API for Conversations:
- REST API Features for Conversations
- Collaboration Resource
- Configuration Resource for Conversations
- Security Resource
- Social Resource
Oracle Content and Experience also provides the following REST APIs:
REST API Features for Conversations
Features of the REST API for Conversations help you develop custom integrations with conversation objects in Oracle Content and Experience.
API Security
All API invocations happen in the security context of the signed-in user.
Agent users can do actions on the system, either independently or on behalf of a particular user. In specific situations you might need to use one of the following properties. Among agent user techniques, as a best practice you should use Impersonate
. Use On Behalf Of
or Bypass
only on the advice of Oracle support or the Oracle integration team.
-
Impersonate
(inXV1ConnectionUpdateInfo
)During the connection to the server, the impersonation sign in is recorded. The server also tracks when the impersonation ends. The audit log tracks the actions as being done by the user being impersonated; it does not track the impersonating agent for each action.
The permissions for actions are based on the permission level of the user being impersonated.
Impersonate
is intended for use only in automated processes, such as for conversation object updates where you want to show that the update was made by a particular user. Keep in mind that usingImpersonate
can degrade analytics accuracy because it associates actions with the impersonated user. -
On Behalf Of
(inXV1ConnectionUpdateInfo
) - Allows a user to do a limited number of end-user functions on behalf of another user, such as posting a message to a Conversation or uploading a document. When this privilege is used, the audit log indicates both the user who performed the action and the user on whose behalf it was performed; in clients, the action is labeled as having been performed by the user the action was performed for. -
Bypass
(in XV1SocialObjectRole, XV1ConversationRole
, andXV1SocialObjectRole
) - Allows the user to do any action without failing due to inadequate permissions (although a request might fail for another reason, such as not being a member of the Conversation being acted on). The Bypass privilege is intended for use only in certain automated processes in a highly secure environment.
API Versioning
The current version of the REST API for Conversations is v1. API versions are not tied to releases of Oracle Content and Experience.
The version number is placed in the URL directly following /social/api. For example:
https://<host>[:<port>]/osn/social/api/v1
A GET request to the API endpoint returns a list of the top-level URIs that the server supports. For example, this request:
https://<host>[:<port>]/osn/social/api/
VCurrent
identifier, which identifies the most recent release of the server API. The current release is "V1
". The result follows:
{"V1" : "https://osn/api/v1",
}
Case Sensitivity
Case is important throughout the REST API because URLs, methods, names, and object IDs are all case sensitive.
Case is significant in the REST API URLs.
HTTP Methods
The REST API for Conversations supports standard HTTP methods (verbs).
Method | Description |
---|---|
GET |
Retrieve or query resources. If you send a GET request for a specific field's value but that field does not exist, the API returns the field that you passed, with a null value and a status of 200. |
POST |
Create a new instance of a resource, such as a conversation. In addition, you can use POST to create a relationship between two objects. For example, you can use POST to create a Like (Starred) relationship between a user and a conversation. |
PUT |
Update the state of an existing instance of a resource. For example, you can use PUT to change the state of a conversation from |
DELETE |
Delete an existing instance of a resource or delete a relationship between two objects. |
Subset of HTTP Methods Supported by Client
If the client supports only a subset of these HTTP methods, you can tunnel the other methods using the POST method by specifying the desired method in the method query parameter. For example, the DELETE operation can be achieved by doing a POST on a resource with "method=delete" in the query string portion of the URL.
PUT Requests with XUpdater
When updating an object using a PUT request, such as with XConversationUpdater
, you can use XUpdater
to specify the value that you want to change. XUpdater
is a class that represents the DTO for updating objects; the updater
field actually represents a map of field values. For example, XUpdater can be reresented as follows:
{
"updater": "XUpdater"
}
For example, you can use a PUT request to . .
./social/api/v1/conversations/ObjectID
with the request payload {"updater":{"SHORT_NAME":"String
for short name"}}
to change the short name.
XUpdater
is used with Collections, Conversations, Groups, People, and Collaboration objects.
Optional Fields and Default Values for JSON Data Representations
The API reference documentation uses the term optional in describing JSON data representation fields.
Optional has a slightly different meaning depending on the data type:
-
String: default is null if not specified.
-
int: default is zero (0) if not specified.
-
boolean: default is false if not specified.
Return Values
You can control the response payload's content type by specifying the JSON or HTML MIME type in the "Accept" HTTP header.
The content type defaults to 'application/json
'. Examples are presented in JSON.
You can specify the value 'text/html
' to get an HTML version of the JSON that is returned.
Name Patterns
All external class names begin with the letter X, followed by the version number, followed by a noun (for example, Conversation, Message, or People), followed by one or more modifiers, depending on the function of the class.
The following table describes the class name conventions and the associated functions, using the Conversation resource type as an example.
XV1Conversation. . . | Action |
---|---|
Info | Get information about a Conversation (GET). |
CreateInfo | Create a Conversation and set properties (POST). |
FilterInfo | Get Conversations that meet the filter criteria (GET). |
MemberCreateInfo | Add a member to a Conversation and set properties (POST). |
MemberInfo | Get information about a member of a Conversation (GET). |
MessageCreateInfo | Add a message in a Conversation (POST). |
PropertyCreateInfo | Set properties for a Conversation (POST). |
PropertyInfo | Get a property for an existing Conversation (GET). |
PropertyUpdateInfo | Set a property for a Conversation (PUT). |
UpdateInfo | Update attributes for a Conversation (PUT). |
ListInfo | Get a list of all Conversations (GET). |
MemberListInfo | Get a list of all direct members of the Conversation (GET). |
PropertyListInfo | Get a list of all properties for the Conversation (GET) . |
StarListInfo | Get a list of starred Conversations and their messages (GET) . |
XObjectID
Each object in the REST API for Conversations has a unique ID. From that ID, you can load the object, if you have sufficient permissions. Many data transfer objects (DTOs) specify IDs of other objects related to the current object. Some examples include ParentID
, ModifiedByUserID
, CreatedByUserID
, and ConversationID
. These are all links or references to other objects in the system.
Note that the ID
parameter represents a name for fields, an ObjectID or an External ID for Conversation objects, and an Object ID or sign in name for users.
URL Encoding
For readability, examples might be shown in literal text, but your requests should always be URL-encoded (percent-encoded).
For example:
/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true}
This example should be URL-encoded as follows:
/conversations?filter=%7B%22LimitToStarred%22%3Atrue%2C%22ExcludeMuted%22%3Atrue%7D
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.
Filters
Filter capabilities are supported where specified.
To use a filter, specify the filter query argument in JSON format, using URL encoding as appropriate. For example, this request returns starred Conversations but no muted Conversations:
/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true}
Sort Order
The currently assigned sort order determines the order in which results are returned.
You can change the sort order using the SortField field, which is available in XV1ConversationFilterInfo, XV1SocialObjectFilterInfo, and others. For example, this request returns results sorted by Conversation age, with the newest Conversation first:
/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true,"SortField":CONVERSATION_IS_NEW}
Localization
This background information about localization might be useful as you are implementing or troubleshooting an Oracle Content and Experience integration.
Some of the concepts described in this section go beyond the REST API.
Localization is performed according to the following steps:
-
Choose a language locale.
-
If an HTTP request exists and has an X-Waggle-ForceLanguage header, then use the X-Waggle-ForceLanguage header value as the language locale and go to step 2.
-
If a particular user is signed in or otherwise identified, check to see if the user has set a preferred language locale in their user profile. If set, use it and go to Step 2.
A language locale from LDAP will be copied to the user profile in Oracle Content and Experience. If the LDAP realm has
sync-on-authentication
enabled, then for each sign in, the LDAP values will overwrite the user profile settings. However, if the user changes the value in their Oracle Content and Experience profile, it is not written back to LDAP; Oracle Content and Experience does not write any attributes to LDAP.If the LDAP Preferred Language is not supported in Oracle Content and Experience (for example,
ar
), English is displayed regardless of the application default language setting. -
If an HTTP request exists and has an
Accept-Language
header, use theAccept-Language
header to select the language locale.Using the
Accept-Language
header, perform a lookup as described in RFC-4647 section 3.4. This will result in a language locale being chosen based on an exact or partial match of the header, the available translation bundles, and the bundle of last resort. -
If the server has a language locale set, use it.
-
Select the host machine default language locale.
-
-
Choose a translation bundle with the exact or longest possible partial match of the chosen language locale. If no exact or partial match exists, then choose the bundle for English.
Supported Locale Codes
The currently supported locale codes are:
- cs (Czech)
- da (Danish)
- de (German)
- en (English)
- es (Spanish))
- fi (Finnish)
- fr (French)
- fr-CA (French-Canadian)
- hu (Hungarian)
- it (Italian)
- ja (Japanese)
- ko (Korean)
- nl (Dutch)
- no (Norwegian)
- pl (Polish)
- pt-br or pt_BR (Portuguese-Brazilian)
- ro (Romanian)
- ru (Russian)
- sv (Swedish)
- tr (Turkish)
- zh-CN or zh_CN (Chinese-Simplified)
- zh-TW or zh_TW (Chinese-Traditional)
Name Field Length Limit
The Name
field for objects, such as Conversation names or User names, has a length limit of 256 characters.
HTTP Status Codes and Error Handling
HTTP status codes for the Collaboration REST API follow.
Status Code | Description |
---|---|
200 | Request Successful. |
4xx | Bad requests. Invalid URI, invalid body format. |
401 | Unauthorized. Should sign in or get a security token. |
403 | Forbidden. Access denied. |
5xx | Internal server error. |
For all responses, the status code is also available in the actual payload in the StatusCode
field. For all non-HTTP Status 200 responses, a message explaining the cause of the error is available in the return value. For example:
{
"StatusCode" : "401",
"StatusCode" : "Unauthorized",
"ResourceID" : "waggle.modules.realm.InvalidLogin",
"ResourceMessage" : "Login required."
}
Exception Response Fields
Field | Description |
---|---|
statusCode | The HTTP status code. |
statusMessage | The HTTP status message. |
exceptionID | The exception ID. |
exceptionClass | The exception class. |
exceptionMessage | The exception message. |
exceptionDate | The exception date. |
Collaboration Resource
Use the Collaboration resource API endpoints to interact with your cloud resources that enable real-time collaboration between individuals and teams and connect your business processes, enterprise applications, and content.
-
Conversations
-
Members of conversations (direct and indirect)
-
Documents associated with conversations
-
Messages and replies to messages in conversations
-
Followups on messages for users
-
Applinks and hybrid links for conversations
-
Inbound mail tokens
-
Properties and user properties of conversations
-
Likes for conversations and messages
-
Stars for conversations and messages
Also, you can list folder IDs that have associated conversations.
For endpoint descriptions and examples, see "Collaboration" in REST API for Conversations.
Configuration Resource for Conversations
Use the Configuration resource API endpoints to configure resources and services.
-
hasMore
-
items
-
nextURL
-
previousURL
-
total (number of available items)
For endpoint descriptions and examples, see "Configuration" in REST API for Conversations.
Security Resource
Use the Security resource API endpoints to manage connections and access.
With the Security resource, you can manage connections for users and conversations.
For endpoint descriptions and examples, see "Security" in REST API for Conversations.
Social Resource
Use the API endpoints of the Social resource to help users mark favorite conversations and documents and collaborate with each other.
With the Social resource, you can manage followups and stars for users.
To manage collaboration for other users, you need to have a dedicated "Integration User" role. See Functionality Provided Through User Roles in Administering Oracle Content and Experience.
For endpoint descriptions and examples, see "Social" in REST API for Conversations.