Cloud Elementscloud-elements.com/wp-content/uploads/...Guide-V2.pdfsupported Documents Hub endpoint...

Documents Hub Provisioning Guide V2 6/30/2014 V1.1

Page 1

Cloud Elements Documents Hub Provisioning Guide

API Version 2.0


Page 2

Table of Contents

Introduction Set up your Application with the Endpoint Sign up for the Cloud Elements Service Provision the Documents Hub Elements via the Cloud Elements Provisioning API

Single Application User Multiple Application Users

REST API Documentation Get Elements OAuth Information

Example Create Instance

Example Get Element

Example Get Elements

Example Get Instance

Example Get Instances

Example Update Instance

Example Delete Instance

Example Handle Callback from the Endpoint Use The Documents Hub In Your Application

Ping Upload File Retrieve a File Retrieve Links Delete a File

By Path By Id

Search List Folder Contents

By Path By Id

Copy File By Path

Update a File Create a Folder Get Storage Usage For Provider

Appendix


Page 3

OAuth Overview Standard OAuth Exchange OAuth with Document Hub Element Provisioning

Create a new Dropbox platform application Create a new Box platform application Create a new Google Drive platform application Create a new OneDrive platform application Create a new SharePoint platform application


Page 4

Introduction The Documents Hub provides a uniform API to allow applications to use various endpoints such as Box, Dropbox, Google Drive, OneDrive and SharePoint.

The following illustration shows the overall flow of the Documents Hub Element provisioning process.

In order to use one or more of the Documents Hub Elements in your application, via the uniform API, you have to first follow three steps:

1. Set up your application with the Documents Hub Element endpoint, e.g., Box, Dropbox, etc.

2. Sign up for the Cloud Elements Services.


Page 5

3. Provision the Documents Hub Element.

The following sections will guide you through this process.

OAuth is an open standard for authorization. Cloud Elements uses OAuth to interact with Elements in the Documents Hub during the provisioning process. For more information on OAuth see OAuth Overview in the Appendix.

Set up your Application with the Endpoint The Appendix contains instructions to set up your application with the endpoint for each supported Documents Hub endpoint (Dropbox, Box, Google Drive, OneDrive and SharePoint).

After following one of these guides, the next step in the process is to sign up for the Cloud Elements service. The remainder of this guide assumes the use of Dropbox.

Sign up for the Cloud Elements Service


Page 6

To sign up for the Cloud Elements service, using a web browser, go to https://console.cloud-elements.com. To ensure security, you will need to sign up using a web browser, versus using the API, so you can keep your organization and user secrets (assigned during the sign up process) secure.

You can sign up for the Cloud Elements service using your GitHub account, or create a new account with Cloud Elements using the "Sign Up" link shown above.

If you choose to not use GitHub to sign up, you will then be required to validate your new account, and will then be required to reset your password.

After completing this process, choose the user Profile Settings as shown below to reset and retrieve the Organization and User secret.


Page 7

At the bottom of the next screen, you will see your user and organization secrets, which you need to reset, copy and make a note of. These secrets will be used in the Element provisioning process.

You’re now ready to start provisioning the Documents Hub Elements via the Cloud Elements Provisioning APIs.


Page 8

Provision the Documents Hub Elements via the Cloud Elements Provisioning API Before we start provisioning Elements, we need to understand how your application will use the Documents Hub Elements. There is currently one provisioning model for all Elements:

1. Single application user for your organization.

2. Multiple application users for your organization.

Single Application User

The workflow for single application users is shown below.


Page 9

Multiple Application Users This model allows multiple application users of demonstrab.ly to provision Elements and in turn, use endpoint services via the Elements.

The following illustration shows how your application, demonstrab.ly, will access the various endpoints via the Documents Hub, via multiple users of the application.


Page 10

Your application, demonstrab.ly, will create a user in the Cloud Elements demonstrab.ly account, associated with each application user that needs to use the Documents Hub Elements. The demonstrab.ly account is simply a wrapper for all the users, and is implicitly created upon signup.

Note: The demonstrab.ly application is not required to pass any user information other than a user ID to Cloud Elements. The user ID is encrypted at rest.

The multiple users provisioning flow is the same as the flow for single users provisioning shown on the previous page.


Page 11

REST API Documentation

Note: The complete documentation for the Documents Hub API can be found at:

https://console.cloud-elements.com/elements/api-docs/#!/documents

The documentation for the Provisioning API can be found at:

https://console.cloud-elements.com/elements/api-docs/#!/instances

and

https://console.cloud-elements.com/elements/api-docs/#!/elements

The following sections describe the API to use for each step in the above flowchart. Provisioning is done through a REST API, implying that each request is described by the HTTP verb and the url to which the request is made.

There are 5 parts to an HTTP request that are required by the Cloud Elements API.

1. HTTP Headers: headers that are required for each request 2. HTTP Verb: the verb that must be used in the request 3. Request URL: the form of the URL where to make the request 4. Request Body: the text of the request body in JSON format 5. Query Parameters: a query string that is appended to the URL

Get Elements OAuth Information HTTP Header: None HTTP Verb: GET Request URL: /elements/{elementKeyorId}/oauth Request Body: None Query Parameters: apiKey- the key obtained from registering your app with the provider, apiSecret - the secret obtained from registering your app with the provider, callbackUrl - the URL that you supplied to the provider when registering your app, state - any custom value that you want passed to the callback handler listening at the provided callback URL. Description: The result of this API invocation is an OAuth redirect URL from the endpoint. Your application should now redirect to this URL, which in turn will present the OAuth authentication and authorization page to the user.


Page 12

A sample request illustrating the API is shown below.

Input Query Parameters ?apiKey=za6jhr3hychnef0&apiSecret=eghxt92pr5xjkuv&callbackUrl=https://www.cloud-elements.com&state : "any custom value to pass in"

Successful Response JSON {"element":"dropbox","oauthUrl":"https://www.dropbox.com/1/oauth2/authorize?response_type=code&client_id=za6jhr3hychnef0&redirect_uri=https%3A%2F%2Fwww.cloud-elements.com&state=dropbox"}

Example Request curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/dropbox/oauth?apiKey=fake_dropbox_api_key&apiSecret=fake_dropbox_api_secret&callbackUrl=http:://fake.oauth.callback/url&state=joseph-blue-palaski'

Response { "element": “dropbox”, "oauthUrl": "https://www.dropbox.com/1/oauth2/authorize?response_type=code&client_id=zulws95ofcvhel5&redirect_uri=http%3A%2F%2Ffake.oauth.callback%2Furl&state=joseph-blue-pulaski" }

Create Instance


Page 13

HTTP Headers: Authorization HTTP Verb: POST Request URL: /instances Request Body: Required - see below Query Parameters: code - the authorization code that is obtained from the provider’s server in the URL query string when the redirect_URL is invoked by the server. Description: An Element token is returned upon successful execution of this API. This token needs to be retained by the application for all subsequent requests involving this element instance.

A sample request illustrating the /instances POST API is shown below.

HTTP Headers Authorization : User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>

Input JSON { "element" : { "key" : "dropbox" }, "configs" :[ { "key": "oauth.callback.url", "propertyValue": "https://www.cloud-elements.com"}, { "key": "oauth.api.key", "propertyValue" : "za6jhr3hychnef0"}, { "key": "oauth.api.secret", "propertyValue" : "eghxt92pr5xjkuv"}], "name" :"<INSERT_INSTANCE_NAME>" }

If the user doesn’t specify a required config entry, an error will result notifying her which entries she is missing.

Successful Response JSON


Page 14

{ "id": 27, "name": "Peter", "token": "BUIWhN8NTPaeyYo7Kblo91CJ1tCG6PUonwnV/XJjy2A=", "element": { "id": 14, "name": "Dropbox", "key": "dropbox", "description": "One place for all your stuff, wherever you are. Dropbox is a free service that lets you bring your photos, docs, and videos anywhere and share them easily. Anything you add to Dropbox will automatically show up on all your computers, phones and even the Dropbox website.", "active": true, "deleted": false, "typeOauth": true, "trialAccount": false, "existingAccountDescription": "Give your application access to your existing Dropbox accountEnter your credentials and details for your Dropbox Account", "configDescription": "If you do not have an Dropbox account, you can create one at <a href=\"http://www.dropbox.com\" target=\"_blank\">Dropbox Signup</a>", "signupURL": "http://www.dropbox.com", "elementProvisionType": "OAUTH_TEMPLATE" }, "tags": [ { "id": 12, "name": "Peter" } ], "provisionInteractions": [], "valid": true, "disabled": false }

Example Request curl -X POST \ -H 'Authorization: \ User 39fceb6cdfd3363d7c5d3ad1a6ae2b4c, \ Organization 6d0c70e362c3ecc7fc8bab5d3d6a30e3' \ -H 'Content-Type: application/json' \ -d @create-instance.json \ 'https://console.cloud-elements.com/elements/api-v2/instances?code=QzwVTfgEv4IAAAAAAAAAH2O483kmzk5Bf3vbYvd8O6I'

create-instance.json


Page 15

{ "element" : { "key" : "dropbox" }, "configs" :[ { "key": "oauth.callback.url", "propertyValue": "http://fake.oauth.callback/url"}, { "key": "oauth.api.key", "propertyValue" : "fake_dropbox_api_key"}, { "key": "oauth.api.secret", "propertyValue" : "fake_dropbox_api_secret"}], "name" :"fake_instance_to_provision" }

Response { "id": 27, "name": "Peter", "token": "BUIWhN8NTPaeyYo7Kblo91CJ1tCG6PUonwnV/XJjy2A=", "element": { "id": 14, "name": "Dropbox", "key": "dropbox", "description": "One place for all your stuff, wherever you are. Dropbox is a free service that lets you bring your photos, docs, and videos anywhere and share them easily. Anything you add to Dropbox will automatically show up on all your computers, phones and even the Dropbox website.", "active": true, "deleted": false, "typeOauth": true, "trialAccount": false, "existingAccountDescription": "Give your application access to your existing Dropbox accountEnter your credentials and details for your Dropbox Account", "configDescription": "If you do not have an Dropbox account, you can create one at <a href=\"http://www.dropbox.com\" target=\"_blank\">Dropbox Signup</a>", "signupURL": "http://www.dropbox.com", "elementProvisionType": "OAUTH_TEMPLATE" }, "tags": [ { "id": 12, "name": "Peter" } ], "provisionInteractions": [],


Page 16

"valid": true, "disabled": false }

Get Element HTTP Headers: None HTTP Verb: Get Request URL: /elements/{elementKeyorId} Request Body: None Query Parameters: None Description: The Element details are returned upon successful execution of this API.

Example

Request curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/elements/14' OR curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/elements/dropbox'

Response


Page 17

{ "id": 14, "name": "Dropbox", "key": "dropbox", "description": "One place for all your stuff, wherever you are. Dropbox is a free service that lets you bring your photos, docs, and videos anywhere and share them easily. Anything you add to Dropbox will automatically show up on all your computers, phones and even the Dropbox website.", "active": true, "deleted": false, "typeOauth": true, "trialAccount": false, "existingAccountDescription": "Give your application access to your existing Dropbox accountEnter your credentials and details for your Dropbox Account", "configDescription": "If you do not have an Dropbox account, you can create one at <a href=\"http://www.dropbox.com\" target=\"_blank\">Dropbox Signup</a>", "signupURL": "http://www.dropbox.com", "elementProvisionType": "OAUTH_TEMPLATE" }

Get Elements HTTP Headers: None HTTP Verb: Get Request URL: /elements Request Body: None Query Parameters: None Description: The Element details are returned upon successful execution of this API.

Example

Request curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/elements'

Response (truncated)


Page 18

[ { "id": 17, "name": "Instagram", "key": "instagram", "description": "Instagram", "active": true, "deleted": false, "typeOauth": false, "trialAccount": true, "configDescription": "If you do not have an Instagram account, you can create one at <a href=\"http://www.instgram.com\" target=\"_blank\">Instgram Signup</a>" }, { "id": 13, "name": "Dropbox OAuth", "key": "dropboxoauth", "description": "Dropbox OAuth 1.0", "active": true, "deleted": false, "typeOauth": false, "trialAccount": true, "configDescription": "If you do not have an Dropbox account, you can create one at <a href=\"http://www.dropbox.com\" target=\"_blank\">Dropbox Signup</a>", "signupURL": "http://www.dropbox.com" } ]

Get Instance HTTP Headers: Authorization - see below HTTP Verb: Get Request URL: /instances/{instanceId} Request Body: None Query Parameters: None Description: The instance details corresponding to the provided id are returned upon successful execution of this API.

Example

HTTP Headers


Page 19

Authorization : User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>

Request curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/instances/18'

Response { "id": 18, "name": "Peter", "token": "dcW8GoJHz+MYhWQmkFA1vcx70WDPPn0voBEx7KUsEKI=", "element": { "id": 14, "name": "Dropbox", "key": "dropbox", "description": "One place for all your stuff, wherever you are. Dropbox is a free service that lets you bring your photos, docs, and videos anywhere and share them easily. Anything you add to Dropbox will automatically show up on all your computers, phones and even the Dropbox website.", "active": true, "deleted": false, "typeOauth": true, "trialAccount": false, "existingAccountDescription": "Give your application access to your existing Dropbox accountEnter your credentials and details for your Dropbox Account", "configDescription": "If you do not have an Dropbox account, you can create one at <a href=\"http://www.dropbox.com\" target=\"_blank\">Dropbox Signup</a>", "signupURL": "http://www.dropbox.com", "elementProvisionType": "OAUTH_TEMPLATE" }, "provisionInteractions": [], "valid": true, "disabled": false }

Get Instances HTTP Headers: Authorization - see below HTTP Verb: Get Request URL: /instances


Page 20

Request Body: None Query Parameters: None Description: The details for all the instances belonging to the user are returned upon successful execution of this API.

Example


Request curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/instances'

Response (truncated) [ { "id": 19, "name": "jt1", "token": "gVlC6V/lzi3MVKjHHYWmIWg+bAj6nXqrTvLQ/yt4uH8=", "element": { "id": 34, "name": "OneDrive", "key": "onedrive", "description": "The OneDrive Element simplifies the way you search, store, retrieve and manage documents and files, by allowing you to integrate a leading cloud document service in a fraction of the time, with a fraction of the code. Any documents and files you store in the cloud can now be found all in one place, integrated seamlessly into your application.", "active": true, "deleted": false, "typeOauth": true, "trialAccount": false, "existingAccountDescription": "Give your application access to your existing OneDrive accountEnter your credentials and details for your OneDrive Account",


Page 21

"configDescription": "SkyDrive configuration", "elementProvisionType": "OAUTH_TEMPLATE" }, "tags": [ { "id": 13, "name": "jt1" } ], "valid": true }, { "id": 22, "name": "Peter", "token": "PIOZbd5+wRLIWz+da1Xu5l/xpcwrGhWYTHbV1EKRTH0=", "element": { "id": 34, "name": "OneDrive", "key": "onedrive", "description": "The OneDrive Element simplifies the way you search, store, retrieve and manage documents and files, by allowing you to integrate a leading cloud document service in a fraction of the time, with a fraction of the code. Any documents and files you store in the cloud can now be found all in one place, integrated seamlessly into your application.", "active": true, "deleted": false, "typeOauth": true, "trialAccount": false, "existingAccountDescription": "Give your application access to your existing OneDrive accountEnter your credentials and details for your OneDrive Account", "configDescription": "SkyDrive configuration", "elementProvisionType": "OAUTH_TEMPLATE" }, "tags": [ { "id": 12, "name": "Peter" } ], "valid": true } ]

Update Instance HTTP Headers: Authorization - see below HTTP Verb: PUT Request URL: /instances/{id} Request Body: Required - see below Query Parameters: None Description: The Element details are returned upon successful execution of this API.


Page 22


Request Body {

"name": "instances-dropbox-api",

"element": {

"key": "dropbox"

},

"tags": [

{

"name": "instance-dropbox-tag-1"

},

{


},

{


},

{


}

],


Page 23

"configs": [

{

"key": "document.tagging",

"propertyValue": true

},

{

"key": "oauth.api.key",

"propertyValue": "zulws95ofcvhel5"

},

{

"key": "oauth.api.secret",

"propertyValue": "bvkridbs3pe0r57"

},

{

"key": "oauth.callback.url",

"propertyValue": "http://localhost:9200/demo/Authz.groovy"

}

]

}

Example


Input JSON


Page 24

{ "name": "instances-dropbox-api", "element": { "key": "dropbox" }, "tags": [ { "name": "instance-dropbox-tag-1" }, { "name": "instance-dropbox-tag-2" }, { "name": "instance-dropbox-tag-3" }, { "name": "instance-dropbox-tag-4" } ], "configs": [ { "key": "document.tagging", "propertyValue": true }, { "key": "oauth.api.key", "propertyValue": "zulws95ofcvhel5" }, { "key": "oauth.api.secret", "propertyValue": "bvkridbs3pe0r57" }, { "key": "oauth.callback.url", "propertyValue": "http://localhost:9200/demo/Authz.groovy" } ] }

Request curl -X GET \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v2/instances/118'


Page 25

Response (truncated) { "id": 118, "name": "Instagram", "key": "instagram", "description": "Instagram", "active": true, "deleted": false, "typeOauth": false, "trialAccount": true, "configDescription": "If you do not have an Instagram account, you can create one at <a href=\"http://www.instgram.com\" target=\"_blank\">Instgram Signup</a>" }

Delete Instance HTTP Headers: Authorization - see below HTTP Verb: DELETE Request URL: /instances/{id} Request Body: None Query Parameters: None Return Value: None Description: The Element instance is deleted for the provided element instance id upon successful execution of this API.

Example


Request curl -X DELETE \ -H 'Authorization: \ User 39fceb6cdfd3363d7c5d3ad1a6ae2b4c, \ Organization 6d0c70e362c3ecc7fc8bab5d3d6a30e3' \ 'https://console.cloud-elements.com/elements/api-v2/instances/118'


Page 26

Handle Callback from the Endpoint Upon successful authentication and authorization by the user, the endpoint will redirect to the callback URL you provided when you setup your application with the endpoint, in our example, https://www.demonstrab.ly/authz.

The endpoint will also provide two query string parameters: "state" and "code". The value for the "state" parameter will be the name of the endpoint, e.g., "dropbox" in our example, and the value for the "code" parameter is the code required by Cloud Elements to retrieve the OAuth access and refresh tokens from the endpoint.

If the user denies authentication and/or authorization, there will be a query string parameter called "error" instead of the "code" parameter. In this case, your application can handle the error gracefully.


Page 27

Use The Documents Hub In Your Application Now that you have finished provisioning your Dropbox Element, you are ready to use the Document APIs to manipulate files and folders in your Dropbox account. Below are examples for each of the Documents Hub APIs.

Note: Any of the tag APIs require that you chose to enable tagging when you provisioned your Documents Hub Element.

Ping

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/ping' { "dateTime": "2014-06-30T08:26:34-06:00", "endpoint": "onedrive" }

Upload File

curl -X POST \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ -F [email protected] \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/files?path=/test.txt&description=Test%20file&tags=ow|now|brown|cow&overwrite=false'


Page 28

{ "id": "file.7fb5056a27bdeac7.7FB5056A27BDEAC7!330", "directory": false, "name": "test.txt", "path": "/test.txt", "size": 14 }

Retrieve a File

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/files/?path=/Running/marathon_smart_coach_plan.pdf' <FILE DATA>

Retrieve Links

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/files/links?path=/test.txt’

{ "providerViewLink": null, "providerLink": "https://ay2pfw.by3302.livefilestore.com/y2mKqQciIreNjozr4sWiT06gTz_Sr_RmLj_ib37LPE07RgLuUm2b_iQUN2id8QdQcK-81-e1rqufIbgoIxaa1xa3pJS-9oeS_UwaGVR91zMIN0/test.txt?psid=1", "cloudElementsLink": "http://localhost:8080/elements/api-v2/external/documents/files?key=p9a213e22-45a7-4f60-9204-f16a88730543_61f3a73261d535511cbfed523c925dd63b902ee654c5f9677eff3673e0770e00" }


Page 29

Delete a File

By Path curl -X DELETE \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/files?path=/test.txt&emptyTrash=false'

By Id

curl -X DELETE \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/files/7FB5056A27BDEAC7'

Search

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/search?path=/Running&text=*&startTime=01-01-2012%2011:11:11&endTime=01-01-2015%2011:11:11&pageNumber=1&pageSize=100'


Page 30

[ { "name": "Documents", "description": "", "path": "/Documents", "directory": true, "id": "folder.7fb5056a27bdeac7.7FB5056A27BDEAC7!114" } ]

List Folder Contents

By Path curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/list?path=/&fetchTags=true&pageNumber=1&pageSize=100'

By Id curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/list/7FB5056A27BDEAC?fetchTags=true&pageNumber=1&pageSize=100'

Copy File

By Path


Page 31

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ -H 'Content-Type: application/json' \ -d @copy.json \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/copy?path=/sourcefile.txt'

By Id

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ -H 'Content-Type: application/json' \ -d @copy.json \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/copy/7FB5056A27BDEAC' copy.json

{ "path": "/destinationfile.txt" }

{ "directory": true, "path": "/destinationfile.txt" }

Update a File


Page 32

curl -X PATCH \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ -H 'Content-Type: application/json' \ -d @rename.json \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/files/metadata?path=/oldfilename.txt' rename.json

{ "path": "/newfilename.txt" }

{ "id": "file.7fb5056a27bdeac7.7FB5056A27BDEAC7!330", "directory": false, "description": "", "name": "test.txt", "path": "/a.txt" }

Create a Folder

curl -X POST \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b', \ 'User 852e8bad78b4eab8cea6e912cfad6b4b', \ 'Organization 852e8bad78b4eab8cea6e912cfad6b4b' \ -H 'Content-Type: application/json' \ -d @create-folder.json \ 'https://console.cloud-elements.com/elements/api-v2/hubs/documents/folders' create-folder.json

{ "path": "/newFolder" }


Page 33

{ "id": "folder.7fb5056a27bdeac7.7FB5056A27BDEAC7!333", "directory": true, "description": "", "name": "newFolder" }

Get Storage Usage For Provider

curl -X GET \ -H 'Authorization: Element 852e8bad78b4eab8cea6e912cfad6b4b' \ -H 'Content-Type: application/json' \ 'https://console.cloud-elements.com/elements/api-v1/document/usage'

{ "shared": 0, "total": 7516192768, "used": 7013104 }


Page 34

Appendix

OAuth Overview

OAuth is an open standard for authorization. Cloud Elements uses OAuth to interact with elements in the Document Hub during the provisioning process.

Standard OAuth Exchange

The diagram below shows a standard OAuth interaction with a service endpoint. An application user performs an action that requires access to a service endpoint. The application then redirects to a well-known OAuth URL for the service endpoint. The user logs in, if necessary, and grants access to the application.

After access is granted, the service endpoint redirects to the URL configured in the "Set up your Application with the Endpoint" section. The redirect URL includes a code that the application exchanges for OAuth access and refresh tokens. These tokens are then used in subsequent API requests between the application and endpoint. Each endpoint has different expiration intervals for the tokens, which the application must manage.


Page 35

OAuth with Document Hub Element Provisioning

The diagram below shows how Cloud Elements uses OAuth during element provisioning. An application user performs an action that requires access to a service endpoint. The application requests the OAuth URL for the service endpoint from Cloud Elements, then redirects. The user logs in, if necessary, and grants access to the application.

After access is granted, the service endpoint redirects to the URL configured in the "Set up your Application with the Endpoint" section. The redirect URL includes a code that the application uses to create an element instance. Cloud Elements uses this code to exchange for OAuth access and refresh tokens. Cloud Elements stores these tokens before responding to the instance creation request with the element information, including an element instance token. The application then uses the element instance token to make Cloud Elements uniform API requests. Cloud Elements makes endpoint API requests using the OAuth tokens obtained from the endpoint.

Each vendor's OAuth implementation varies slightly, but these details are handled by Cloud Elements. Cloud Elements also manages the app's OAuth access and refresh tokens


Page 36

internally. The user does not need to worry about storing these tokens or refreshing them when they expire.

Create a new Dropbox platform application In this section, we will use Dropbox as the example to set up your application with the endpoint.

Via a web browser, go to https://www.dropbox.com/developers/apps/create.

Select the Dropbox API app option, select the appropriate options and enter a name for your application.

For this example, let’s assume that the URL for your application is https://www.demonstrab.ly.


Page 37

On the next screen, you’ll be required to enter a callback URL from the endpoint. This URL will be in your application’s address space. You will be required to retrieve some information returned on this URL by the endpoint. The details of handling the callback are elsewhere in this document.


Page 38

For our example, we’ll use a callback URL of https://www.demonstrab.ly/authz. Enter this URL on the following screen at Dropbox.

Please make a note of the "App key" and "App secret" assigned by Dropbox for the Demonstrab.ly application.

Create a new Box platform application In this section, we will use Box as the example to set up your application with the endpoint.

Via a web browser, go to https://app.box.com/developers/services/edit/.


Page 39

Enter the name of your application, select the appropriate options and click "Create Application".


After receiving confirmation that your application is created, click "Configure your application".


Page 40



Page 41

For our example, we’ll use a callback URL of https://www.demonstrab.ly/authz. Enter this URL on the following screen at Box.

Please make a note of the "client_id" and "client_secret" assigned by Box for the Demonstrab.ly application.

Create a new Google Drive platform application


Page 42

In this section, we will use Google Drive as the example to set up your application with the endpoint. Further details on this process are documented at https://developers.google.com/drive/web/enable-sdk.

Via a web browser, go to https://console.developers.google.com.

Click on "Create Project". Enter a title and project ID (or use the auto-generated ID), and click "Create".


After receiving confirmation that your application is created, click "APIs & auth" and then "Credentials". In the OAuth Section, click "Create New Client ID".


Page 43


For our example, we’ll use a callback URL of https://www.demonstrab.ly/authz. Enter this URL on the following screen on the Google Developers Console. Enter the required information and click "Create Client ID".


Page 44

After a few moments, the Client ID information for your application will appear on the console, as shown below.


Page 45

Please make a note of the "Client ID" and "Client secret" assigned by Google for the Demonstrab.ly application.

Create a new OneDrive platform application In this section, we will use OneDrive as the example to set up your application with the endpoint.

Via a web browser, go to https://account.live.com/developers/applications/create.

Enter a name for your application and click "I accept".



Page 46

On the next screen, click "API Settings" and enter a callback URL from the endpoint. This URL will be in your application’s address space. You will be required to retrieve some information returned on this URL by the endpoint. The details of handling the callback are elsewhere in this document.

For our example, we’ll use a callback URL of https://www.demonstrab.ly/authz. Enter this URL and click "Save".

Click on "App Settings" to view OAuth keys.


Page 47

Please make a note of the "Client ID" and "Client secret" assigned by Microsoft for the Demonstrab.ly application.

Create a new SharePoint platform application In this section, we will use Microsoft SharePoint as the example to set up your application with the endpoint.

Via a web browser, go to http://yourSharePointServerName/_layouts/15/appregnew.aspx.

Select the "An app running on a web server" option, select the appropriate options and enter a name for your application.

For this example, let’s assume that the URL for your application is https://www.demonstrab.ly. You’ll also be required to enter a callback URL from the endpoint. This URL will be in your application’s address space. You will be required to retrieve some information returned on this URL by the endpoint. The details of handling the callback are elsewhere in this document.

For our example, we’ll use a callback URL of https://www.demonstrab.ly/authz. Enter this URL on the App information screen in SharePoint.

Click the "Generate" buttons for both the "Client Id" and "Client Secret" fields. Finally, click the "Create" button to register the app with your SharePoint instance.


Page 48

On the next page, you should receive confirmation that your app was created successfully, as shown below.

Please make a note of the "Client Id" and "Client Secret" assigned by SharePoint for the Demonstrab.ly application.

Date post:	27-Jul-2020
Category:	Documents
Upload:	others
View:	6 times
Download:	0 times