REST Interfaces for Configuration, Authorization, and Fetching Content

A content connector needs to implement the following REST APIs for defining the connector configuration, setting up authorization, and fetching content.

/rest/api

Implements intradoc.connectorcommon.server.APIResource

Here you return the latest version supported by the content connector.

GET http://host:port/connector/rest/api

[    "v1"]

/rest/api/v1/server

Implements intradoc.connectorcommon.server.ServerResource

This returns information about the content connector configuration, like the authentication type, picker type, and custom fields it exposes.

GET http://host:port/connector/rest/api/v1/server

{
    "name": "Pexels Connector",
    "nameLocalizations": [
        {
            "locale": "en",
            "localizedString": "Pexels Connector"
        }
    ],
    "version": " (, , )",
    "about": "Pexels Connector.<br>Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.",
    "aboutLocalizations": [
        {
            "locale": "en",
            "localizedString": "Pexels Connector.<br>Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved."
        }
    ],
    "authenticationType": "NO_AUTH",
    "pickerType": "CUSTOM",
    "enableMultiUserCopyBack": false,
    "maxUploadSize": 1073741824,
    "fields": [
        {
            "ID": "ProxyHost",
            "datatype": "STRING",
            "siteSettable": true,
            "userSettable": false,
            "connectorSettable": false,
            "authorizationURLParameter": false,
            "label": "HTTP Proxy Hostname",
            "labelLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "HTTP Proxy Hostname"
                }
            ],
            "description": "The HTTP proxy hostname, leave blank to disable.",
            "descriptionLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "The HTTP proxy hostname, leave blank to disable."
                }
            ],
            "required": false
        },
        {
            "ID": "ProxyPort",
            "datatype": "STRING",
            "siteSettable": true,
            "userSettable": false,
            "connectorSettable": false,
            "authorizationURLParameter": false,
            "label": "HTTP Proxy Port",
            "labelLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "HTTP Proxy Port"
                }
            ],
            "description": "The HTTP proxy port number, leave blank to default to port 80.",
            "descriptionLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "The HTTP proxy port number, leave blank to default to port 80."
                }
            ],
            "required": false
        },
        {
            "ID": "ProxyScheme",
            "datatype": "STRING",
            "siteSettable": true,
            "userSettable": false,
            "connectorSettable": false,
            "authorizationURLParameter": false,
            "label": "HTTP Proxy Scheme",
            "labelLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "HTTP Proxy Scheme"
                }
            ],
            "description": "The HTTP proxy scheme, leave blank to default to http.",
            "descriptionLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "The HTTP proxy scheme, leave blank to default to http."
                }
            ],
            "required": false
        },
        {
            "ID": "ClientID",
            "datatype": "STRING",
            "siteSettable": true,
            "userSettable": false,
            "connectorSettable": false,
            "authorizationURLParameter": false,
            "label": "Client ID",
            "labelLocalizations": [
                {
                    "locale": "en",
                    "localizedString": "Client ID"
                }
            ],
            "description": null,
            "descriptionLocalizations": [],
            "required": true
        }
    ],
    "supportedConnectorTypes": [
        "COPY"
    ],
    "proprietorName": "",
    "serviceProviderName": "Pexels",
    "nativeAppInfos": null
}

/rest/api/v1/authorization/authorizationURLs

Implements intradoc.connectorcommon.server.AuthorizationResource

This is required only if the content connector supports OAuth.

It returns the authorization URL to which the browser will redirect to invoke the OAuth flow where the user provides credentials and authorizes the access. The redirect URL passed in the payload is what the OAuth provider will redirect to with the temporary code.

POST http://host:port/connector/rest/api/v1/authorization/authorizationURLs

Headers
Content-Type:application/json
X-CEC-ClientID:client-id
X-CEC-ClientSecret:client-secret
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http
  
Payload
{"redirectURL":"http://host:port/documents/web/AR_COMPLETE_AUTHORIZATION"}
  
Response
{
    "authorizationURL": "https://domain/oauth/authorize?response_type=code&client_id=id://host:port/documents/web/AR_COMPLETE_AUTHORIZATION",
    "fieldValueMap": null
}

/rest/api/v1/authorization/completedAuthorizations

Implements intradoc.connectorcommon.server.AuthorizationResource

This is required only if the content connector supports OAuth.

This is called to complete the second part of the OAuth flow, where the code obtained from the OAuth provider in the previous step is passed along with the client ID and secret to obtain the access token and refresh token along with expiry times. This information is then returned to Oracle Content Management, which stores it securely against the signed-in user.

POST http://host:port/connector/rest/api/v1/authorization/completedAuthorizations

Headers
Content-Type:application/json
X-CEC-ClientID:client-id
X-CEC-ClientSecret:client-secret
X-CEC-code:code
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http
Content-Type:application/json
  
Payload
{"redirectURL":"http://host:port/documents/web/AR_COMPLETE_AUTHORIZATION"}
  
Response
{
    "authorized": true,
    "authorizedUserDisplayName": null,
    "authorizedUserEmailAddress": null,
    "authorizedUserPictureURL": null,
    "fieldValueMap": {
        "RefreshToken": "refresh-token",
        "AccessToken": "access-token"
    }
}

/rest/api/v1/authorization/basicAuthorization

Implements intradoc.connectorcommon.server.AuthorizationResource

This is required only if the content connector supports basic authorization. Here the sign in credentials are passed in the headers where the password field is base64 encoded. It is always recommended that a content connector be deployed on an SSL endpoint.

POST http://host:port/connector/rest/api/v1/authorization/basicAuthorization

POST http://host:port/connector/rest/api/v1/authorization/basicAuthorization

Headers
Content-Type:application/json
X-CEC-UserName:user
X-CEC-UserPwd:password
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http

Response
true

/rest/api/v1/content

Implements intradoc.connectorcommon.server.ContentResource

Given a file ID, this return the input stream for a file.

GET http://host:port/connector/rest/api/v1/content?uri=fFileGUID:xxxx

Request Headers
X-CEC-ClientID:client-id
X-CEC-ProxyHost:proxy-host
X-CEC-ProxyPort:80
X-CEC-ProxyScheme:http
   
Response Headers
content-disposition attachment; filename=pexels-photo-xxxx.jpeg
content-type image/jpeg
  
Response Body
File Content