API OVERVIEW G U I D E Version 1.0

Version 1.0

Copyright © 2018 Accellion, Inc. All rights reserved. These products, documents, and materials are protected by copyright law and distributed under licenses restricting use, copying, distribution, and decompilation. Accellion and the Accellion logo, are registered trademarks of Accellion, Inc. kiteworks is a trademark of Accellion. All other trademarks are properties of their respective owners.

.2

API OVERVIEW GUIDE

Table of Contents Introduction.......................................................................................................................... 5

kiteworks REST APIs .......................................................................................................................................................... 5

Prerequisites ......................................................................................................................... 5

Sign Up for the Free Enterprise Trial of kiteworks ................................................................. 6

Getting Started ..................................................................................................................... 6

Getting a Token ................................................................................................................................................................. 8

kiteworks Authorization Code (OAuth 2.0 Flow) .............................................................................................................. 9

Obtaining Access Token Requirements ......................................................................................................................... 9

Sequence Overview ....................................................................................................................................................... 9

Step-by-step Usage...................................................................................................................................................... 10

Signature-based Authorization Code .............................................................................................................................. 13

Calculate the Authorization code ............................................................................................................................... 13

Access Token Request ................................................................................................................................................ 14

Execute API Calls ............................................................................................................................................................. 17

Creating API Requests ......................................................................................................... 20

Using API Requests ............................................................................................................. 21

Using id ............................................................................................................................... 22

Creating Objects ................................................................................................................. 25

Adding Files ........................................................................................................................ 30

Adding Large Files ............................................................................................................................................................ 31

Chunk Upload Workflow ................................................................................................................................................. 31

Chunk Upload Process Steps ....................................................................................................................................... 31

Request Body Parameters Description ........................................................................................................................ 32

Retrieve Upload Session Data ..................................................................................................................................... 32

Upload Chunks............................................................................................................................................................. 33

Terminating Upload Session ........................................................................................................................................ 34

NOTES .......................................................................................................................................................................... 34

Downloading Files .............................................................................................................. 36

.3

API OVERVIEW GUIDE

Enabling the kiteworks API Playground UI .......................................................................... 38

Customizing Settings, Scopes and Security ..................................................................................................................... 40

Settings ........................................................................................................................................................................ 40

Scopes .......................................................................................................................................................................... 41

Security ........................................................................................................................................................................ 41

APIs Overview .................................................................................................................... 43

Content APIs .................................................................................................................................................................... 43

users ............................................................................................................................................................................ 43

folders .......................................................................................................................................................................... 43

files .............................................................................................................................................................................. 43

sources ......................................................................................................................................................................... 43

trays ............................................................................................................................................................................. 43

Collaboration APIs .......................................................................................................................................................... 44

mail .............................................................................................................................................................................. 44

comments .................................................................................................................................................................... 44

tasks ............................................................................................................................................................................. 44

Preferences APIs .............................................................................................................................................................. 45

notifications ................................................................................................................................................................. 45

favorites ....................................................................................................................................................................... 45

languages ..................................................................................................................................................................... 45

timezones .................................................................................................................................................................... 45

Contacts APIs ................................................................................................................................................................... 45

contacts ....................................................................................................................................................................... 45

groups .......................................................................................................................................................................... 45

LDAP Groups ................................................................................................................................................................ 45

Security APIs .................................................................................................................................................................... 46

profiles ......................................................................................................................................................................... 46

roles ............................................................................................................................................................................. 46

adminRoles .................................................................................................................................................................. 46

devices ......................................................................................................................................................................... 46

admin ........................................................................................................................................................................... 46

Client Management APIs ................................................................................................................................................. 47

.4

API OVERVIEW GUIDE

clients .......................................................................................................................................................................... 47

scopes .......................................................................................................................................................................... 47

kiteworks Maintenance APIs ........................................................................................................................................... 47

licenses ........................................................................................................................................................................ 47

.5

API OVERVIEW GUIDE

Introduction

The kiteworks RESTful Enterprise APIs enable you to quickly develop apps that leverage the power of the kiteworks Content Platform. The platform provides secure, ubiquitous connectivity to any type of content from any content storage supported by kiteworks, on any device, on-premises or in the cloud. The kiteworks content platform offers developers access to out-of-the box enterprise-grade capabilities for rapidly developing innovative enterprise applications that can securely access, edit, and share enterprise content.

A key component of the platform is the set of RESTful Enterprise APIs that provides developers access to all of the file

sharing, collaboration, and sync capabilities of the kiteworks solution. It saves you years of development because it is

enterprise-ready out of the box. The platform also provides secure, unified connectivity to documents stored in any

content systems, both on-premise systems such as SharePoint and Documentum, as well as cloud systems such as

Google Drive and Dropbox. These powerful APIs enable developers to build custom apps tailored to specific industry

and business use cases, as well as integrate with existing IT infrastructure. For example:

For the auto insurance industry, an insurance broker can manage a repository for the documents related to

each claim. Meanwhile, the claimants, adjusters, vendors and lawyers can use custom mobile apps to check off

tasks as they add and view their photos, documents and forms related to the claim.

A catalog of sales items and marketing collateral can be distributed to a worldwide sales force using tablets.

Automated folder creation and permissions can ensure the right items and collateral are available to the right

people’s tablets at the right time.

A bank can create a deal room for each major deal, and provide secure access to outside parties such as

attorneys, agents and inspectors to upload and review documents using their tablets instead of a fax machine.

kiteworks REST APIs

The kiteworks REST API set are accessible from https://<kiteworks_installation_hostname>/rest/index.html. You can

familiarize yourself and test drive the APIs on this page, before delving into developing your custom app.

Prerequisites

The audience of this guide should be experienced developers on their particular platform and it is assumed that:

They understand the basics of OAuth

They understand the format, structure, and common paradigm of JSON

They can formulate web requests for common methods, e.g., GET, POST, PUT, and DELETE They have a working

knowledge of multipart MIME requests

.6

API OVERVIEW GUIDE

Sign Up for the Free Enterprise Trial of kiteworks

Go to the following URL to sign up:

https://info.accellion.com/mlp-trl-Enterprise-Trial.html

Within a few minutes after signing up, your trial kiteworks system in the cloud will be ready for use. You will receive an

email from provisioning@accellion.com with instructions on how to access it.

NOTE: This trial is not intended for commercial use in a production environment, its sole purpose is for non-production

development and testing.

Getting Started

To start your custom application development, perform the steps below.

1. Sign in to kiteworks.

Once you have your instance of kiteworks up and running, sign in to the kiteworks admin interface with your

user credentials. The admin interface can be accessed from the hostname of your kiteworks server /admin.

2. Create your custom application to obtain the identifying information: the Client ID and Secret Key.

a. On the kiteworks Administrator’s Dashboard, go to Application > Client Management > Custom

Applications and add your custom application.

.7

API OVERVIEW GUIDE

b. Specify a Custom Application Name. This name will be used by the Administrator for the Client Application

Management and Reporting and in the Consent Form to authorize new users.

c. Select the authentication flow that your application will use to obtain an access token. Authorization Code-

Standard OAuth 2.0 authorization-code consists of authorization, consent and the code redemption

process.

Under Flows select Authorization Code.

Specify the Redirect URI using this format https:///oauth_callback.php

Choose your Access Token Lifetime

.8

API OVERVIEW GUIDE

3. Add your Custom Application. You will be given the Client Application ID and Client Secret Key for your

application.

IMPORTANT: You must copy this information and keep it in a secure location. The Client Secret Key is required

for authenticating your app. If you lose this information, you will have to start over and re-register your app.

4. Configure your Custom Application. The kiteworks APIs are used by the custom applications to access user

resources on a kiteworks server.

The kiteworks APIs are used by the custom applications to access user resources on a kiteworks server.

API Usage – The APIs follow the REST architectural style and use the scheme of addressing a resource and invoking a

method on that resource.

The API URI – All APIs can be called using the following URI scheme: https://<hostname>/rest/<resources>/<endpoint>

API Output – The API result is returned in JSON format.

Getting a Token

Select the Get a Token button in the upper right corner of developer documentation page. An example of the token is shown in the upper right field on the Developer Documentation page below. This token is used for all requests sent out from this documentation page.

You can request a token from the following grant types:

Authorization Code

Signature-based Authorization Code

Signature-based Access

User Credential

User Credential (using HTTP Basic Authorization)

.9

API OVERVIEW GUIDE

SAML 2.0 Assertion

JWT Assertion

kiteworks Authorization Code (OAuth 2.0 Flow)

The kiteworks APIs allows any new client application (client for short) to be developed for the kiteworks solution. The

APIs can be used by the client to gain access to resources belonging to a user on the kiteworks server. The APIs can only

be used by a client that is registered on the kiteworks server.

A client must provide an access token to access resources belonging to a user on the kiteworks server. The kiteworks

server provides access token provisioning flows based on the OAuth 2.0 (https://tools.ietf.org/html/rfc6749). The

majority of clients will consume the so-called Authorization Code Flow to obtain an access token. This flow is developed

based on the authorization code grant type of the OAuth 2.0 specification.

This document provides a step-by-step guide for application developers to build a client for consuming the

Authorization Code Flow to obtain an access token and use the access token to access users’ resources on a kiteworks

server. Example codes for Android based clients are also provided.

Obtaining Access Token Requirements

For obtaining an access token using the kiteworks Authorization Code Flow, you need the client registration information

recorded in the previous steps:

client_id – This is a unique system generated id of your client.

client_secret – This secret serves as a password for your client to authenticate itself to the kiteworks server.

b – This is the URI on which your client must listen for the authorization result. For mobile clients or for clients

that cannot be redirected to another service, the landing page https://<kiteworks_server>/oauth_callback.php

can be used.

scope – This is the set of API services that your client wants to access. Consult with your administrator regarding which

scopes are available for your client.

Sequence Overview

The sequence of the Authorization Code Flow is as follows:

1. The client initiates the flow by redirecting the user-agent (browser or web view component) to the appropriate

authorization page on the server. The client includes its ID and a redirect URI to which the server will send the

user back once access is granted or denied.

2. The server authenticates the user using a login page similar to web client login page and establishes whether

the user grants or denies the client's access request.

3. If the user grants access, the server redirects the user-agent to the redirection URI provided earlier. The URI

also includes an authorization code that can be used to request an access token for that user.

4. The client requests an access token from the server by authenticating itself (using its ID and secret) and

including the authorization code received in the previous step.

5. The server validates the client credentials and the authorization code and responds with the access token. The

client uses the access token to invoke APIs for accessing user’s resources.

.10

API OVERVIEW GUIDE

Step-by-step Usage

The request-response of this flow follows the specification of OAuth 2.0 protocol

(http://tools.ietf.org/html/rfc6749#section-4.1). All requests for authorization and for calling service must be done

through HTTPS. The URI end-points of this flow are as follows:

Authorization end-point: https://<hostname>/oauth/authorize

Token end-point: https://<hostname>/oauth/token

All request parameters, unless otherwise specified, must be passed through HTTP POST parameters. The response body

will be in JSON format. The following information describes this in more detail.

Step 1 Authorization Request

The first step is to call the Authorization end-point with the request parameters passed via HTTP GET. Depending on the

case, the user may be prompted with a dialog to authenticate and then to authorize the request for access permission

by the client application. The following parameters must be passed in the request to the Authorize URI (this follows the

OAuth 2 specification).

client_id – is the identifier of the client-application as registered in the server. For example ‘playground’.

redirect_uri – is the URI to which the result of the authorization will be passed. This redirect URI must start

with the URI specified at the time of the creation/registration of the client application. For example, if the client

application had registered with the redirect URI of https://mydomain.com/oauth then the client application

may provide https://mydomain.com/oauth/callback as redirect_uri parameter in this request. Note, that this

parameter must be properly URL-encoded.

response_type – the value of this parameter must be set to “code”.

scope – is the scope of the API services that the client wants to access. This is a space-separated string

consisting of the name of the method and API services that the application requires. For example: “GET/users/*

*/files/*”. The requested scope must be a sub-set of the client application's registered scope in the server. If a

blank scope is provided, the registered scope will be assumed.

m (optional parameter) – set to 1 to display mobile friendly authorization page.

state (optional parameter) – is an optional parameter that the client application may pass in order to maintain

the state of its process. The server will pass back this parameter as-is in the response.

Example:

(Note that line break is used only for clarity)

GET https://kiteworks_server/oauth/authorize?

client_id=abc&response_type=code&scope=&redirect_uri=

https%3A%2F%2Fkiteworks_server%2Foauth_callback.php HTTP/1.1

Successful Response

After the server finishes the authorization and authentication procedure with the user, the server will redirect the user

(via HTTP 302) to the redirect_uri provided in the Authorize call. Two parameters will be passed through this redirection

URI: code and state. The code parameter is the authorization code that can be used to obtain the access token in the

second step.

.11

API OVERVIEW GUIDE

Example

HTTP/1.1 302 Found

Location: https://kiteworks_server/oauth_callback.php?code=60cc146c8dced75e26e

Error Response

If an error occurs (such as invalid consumer id, or invalid redirect URI), an error message will be displayed immediately

within the user’s browser. For other errors (such as invalid scope or denied access by the user) the server will redirect

the user (via HTTP302) to the redirect_URI. The parameters are:

error – is the error code. The following are the possible values of the error code:

o access_denied: The user denied the permission request.

o invalid_scope: The requested scope is invalid.

o invalid_request: The request is missing a required parameter, includes an unsupported parameter or

parameter value, or is otherwise malformed.

o unauthorized_client: The client-application is not authorized to use this flow.

o state – is set to the exact value received in the request.

Example:

HTTP/1.1 302 Found

Location: https:// kiteworks_server/oauth_callback.php?error=access_denied

Step 2 - Access Token Request

The authorization code obtained in the first step can be exchanged for the final access token by making a request to the

access token end-point. The following parameters must be passed to the token end-point as POST parameters:

client_id – is the ID of the client as registered in the server. E.g. ‘playground’.

client_secret – is the client’s secret phrase as registered in the server.

grant_type – its value must be set to authorization_code.

redirect_uri – is exactly the same redirect URI as used in the first step.

code – is the authorization code obtained in the first step.

install_tag_id (optional parameter) – is a string to uniquely identify the device from which the API call has

initiated.

install_name (optional parameter) – is the friendly name of the device from which the API call has initiated.

Example:

(Note that line breaks on the message content are used only for clarity)

POST /oauth/token HTTP/1.1

Host: kiteworks_server

Content-type: application/x-www-form-urlencoded

client_id=abc&client_secret=TheSecret&grant_type=authorization_code&code=c88bc3

6f751549adf60658c2c607a03b52e417bc& redirect_uri=

https%3A%2F%2Fkiteworks_server%2Foauth_callback.php

&install_tag_id=device_123&install_name=user_ipad

.12

API OVERVIEW GUIDE

Successful Response

If the credentials of the client and the authorization code are valid and there is no other error, the server will return a

HTTP response 200 OK. The body of the response is in JSON format with the following information:

access_token – is the token that can be used to request an API service.

expires_in – is the number in seconds after which the access token would expire.

token_type – is set to “bearer”

scope – is the scope for which this token is valid, normally it will be the same as the requested scope.

refresh_token – is the refresh token that can be used to get a new access token without going through Step 1

Authorization Request. This refresh token will be provided only if the client is allowed to use refresh tokens as

specified during client registration.

Example:

HTTP/1.1 200 OK

Cache-Control: no-store

Content-Type: application/json

{"access_token":"d932e1d32d89140163345d47fa97bfa60eeba1a5","expires_in":"360000

","token_type":"bearer", "scope":"GET\/users\/*

*\/files\/*","refresh_token":"d7ce54d721e8das60943f3fc7cb159e4b11d0ee5"}

This access token can then be used to access user's resources through API services.

Error Response

If the credentials of the client or the authorization code is invalid or there is some other error, the server will respond

with HTTP 400 Bad Request. The body of the response will contain the following error information in JSON format:

serror – is the error code. The following are the possible values :

o invalid_client – Client authentication failed. The client ID and/or secret key provided is invalid.

o invalid_grant – The authorization code or redirect URI provided is invalid. invalid_scope – The requested

scope is invalid or exceeds the previously granted scope.

o invalid_request – The request is missing a required parameter, includes an unsupported parameter or

parameter value, or is otherwise malformed.

o unauthorized_client – The client is not authorized to use this flow.

.13

API OVERVIEW GUIDE

Signature-based Authorization Code

Using the OAuth signature flow, an application that is deemed trusted by the kiteworks administrator can obtain a

token. There are two main steps to performing the signature flow. The first is to calculate the authorization flow, and

the second is to request an access token. These two steps are described in detail below:

Calculate the Authorization code

The following parameters are required to calculate the authorization code:

client_id: This is the client application’s ID, which is registered in the server and was given when the client

application was created in the admin UI.

client_signature_key: This is the client application’s signature key. This is also registered in the server and

was given when the client application was created.

user_id: This is the user’s id (either the email address or the integer id associated with the user). This is

required for the client application to access the appropriate resources.

timestamp: This is the timestamp at the time (in UTC) that this signature is generated. The signature code will

only remain valid within an hour of creation.

nonce: A random integer between 1 and 999999.

Using these parameters, the authorization flow can be calculated. First, a base string should be calculated

using the following format:

base_string = client_id|@@|user_id|@@|timestamp|@@|nonce

Here is a sample snippet of Java code to calculate the base string:

//Constructs the base string using elements outlined in the documentation

String baseString + clientId + “|@@}” + userId + “|@@|” + Long.toString(timestamp) +

“|@@|” + Integer.toString(nonce);

From there, the signature of the base string can be calculated, using the HMAC SHA1 method, and using the client

application’s signature key as the HMAC’s key:

signature = HMAC_SHA1(base_string, client_signature_key)

.14

API OVERVIEW GUIDE

Here is a sample method in Java to calculate the signature:

//Used by the authentication method. Gets a signature based on a key and a base string

Private String getSignature(String clientSignatureKey, StringbaseString) throws Exception{

Mac hmacsha1 = Mac.getinstance(“HmacSHA1”);

SecretKeySpec signinKey = new SecretKeySpec(clientSignatureKey.getBytes(), “HmacSHA1”);

Hmacsha1.init(signingKey);

Byte[] rawHmac = hmacsha1.doFinal(baseString.getBytes());

String signature = DatatypeConverter.printHexBinary(rawHmac).toLowercase();

return signature;

]

Finally, the authorization code can be constructed as follows:

auth_code =

base64_encode(client_id)|@@|base64_encode(user_id)|@@|timestamp|@@|nonce|@@|signat

ure

Here is a sample method in Java for calculating the authorization code:

//Used by the authentication method. Gets an auth code based on parameters.

Private String getAuthCode (String clientId, String userId, String timestamp, String nonce, String signature) throws IOException {

//Base 64 encoder

BASE64Encoder encoder = new BASE64Encoder();

//encodes the client id and takes off the last character, as the encoder adds a new line character at the end

String encodedClientId = encoder.encodeBuffer(clientId.getBytes());

encodedClientId = encodedClientId.substring(0, encodedClientId.length() – 1);

//encodes the user id

String encodeUserId = encoder.encodrBuffer(userId.getBytes());

encodeUserId = encodeUserId.substring (0, encodeUserId.length() – 1;v

//Construct auth code

String authCode = encodedClientId + “|@@|” + encodedUserId + “|@@|” + timestamp + “|@@|” + nonce + “|@@|” + signature;

return authcode;

}

Access Token Request

Make a POST request to the token endpoint with the following parameters:

client_id: This is the client application’s ID, which is registered in the server and was given when the client

application was created in the admin UI.

client_secret: This is the client application’s secret phrase, which is registered in the server and was given

when the client application was created in the admin UI.

grant_type: This should be set the string “authorization code” for the token request to work.

scope: This is the scope of the API services that the client application wants to access. This should be a

space­separated string that consists of the name of the services that the application requires. The requested

scope must be a subset of the client application’s registered scope in the server.

redirect_url: This is exactly the same redirect URI as registered with the server.

.15

API OVERVIEW GUIDE

code: This is the authorization code calculated in step one.

install_tag_id (optional parameter): This is a string to uniquely identify the device from which the API call has

initiated.

install_name (optional parameter): This is the friendly name of the device from which the

API call has initiated.

Here is an example of the POST request:

POST /oauth/token HTTP/1.1 Host: kiteworks_server

Content-type: application/x-www-form-urlencoded Content-length: 415

Connection: close

Client_id=playground&client_secret=secret&grant_type=authorization_code&scope=* %2folders%2F*%202F8files%&code=cGxheWdyb3VuZA%3D%7C

%40540%7CdGVzdEBhY2N1bGxpb24uY29t%7C%40%40%7c1407493837%7C%40%40%7C724408%7C %40%40%7C4efc222192b742bd56516004412cce79267b4c02&redirect_url=https%3A%2F%2Fserver.com%2F

Here is a sample method in Java to construct the string of parameters to be sent in the request:

Once these two steps are complete, if there are no errors for the POST request, the server will return a HTTP response

200 OK. The body for the response will be in JSON format and will include the following:

access_token: This is the token that will be used for all requests to the API

expires_in: This is the number of seconds after which the access token will expire

scope: This is the scope for which this token is valid

refresh_token: This is a token that can be used to get a new access token without going through the first step

of authorization

token_type: This will be set to “bearer” because that is the type of token.

//Assembles all of the elements necessary to be passed through the web requested

//to be authenticated successfully

private String getParams(String clientId, String clientSecret, String scope, String redirectUri, StringauthCode) {

String params = "client_id=" + clientId + "&";

params = params + "client_secret=" + clientSecret + "&";

params = params + "grant_type=" + "authorization_code" + "&";

params = params + "scope=" + scope + "&";

params = params + "redirect_uri=" + URLEncoder.encode(redirectUri) + "&";

params = params + "code=" + URLEncoder.encode(authCode);

return params;

}

.16

API OVERVIEW GUIDE

Here is an example of a successful response:

HTTP/1.1 200 OK Cache-Control: no-store Content-Type: application/json

{"access_token":"054915e674bc35fa7fff1f499044e964d3a5d61b","expires_in":3600,"t

oken_type":"bearer,"scope":"*\/folders\/* *\/files\/*",

"refresh_token":"085b8f5e3153c083fdde20d53030b5b623a6ecb3"}

If there are problems with the request, the server will return a HTTP 400 bad request. The body of the response will

contain error information in JSON format. Here are the possible values for the error code:

invalid_client: This indicates that the client application authentication failed. This is likely because either the

client ID and/or the secret key provided are incorrect.

invalid_grant: This indicates that the user’s credentials are not valid.

invalid_scope: This indicates that the requested scope in invalid or exceeds the previously granted scope.

invalid_request: This indicates that the request is malformed, which usually means that there is a missing

parameter that is required.

unauthorized_client: This indicates that the client application is not authorized to use this flow.

Attached is also a Java file called Requests.java that contains a class with a method to perform this flow, using the

sample methods that appear in the text. The method itself is called authenticate and returns a string, which is the

token. Other sample methods are in the file too, for your viewing/altering purposes.

.17

API OVERVIEW GUIDE

Execute API Calls

Now that we have the access token, it is time to get started with using the kiteworks API in your mobile application.

Before we begin, select the value of the access token returned from the response executed in the previous step. From

the example response the value is: d932e1d32d89140163345d47fa97bfa60eeba1a5 Paste the token in the input field

of the Developer Documentation page as shown below.

Let us begin with performing a basic API call. In the body of the webpage, there is a list of entities, each of which

correspond to a different part of kiteworks and is represented with a JSON payload. When an entity name is clicked, the

interface will expand to show all of the endpoints associated with that entity. An endpoint is a web request that

performs a task related to the entity it falls under.

As an example, navigate to the users entity.

Here, you can see the list of endpoints associated with the users entity. For clarity purposes, they are color coded based

on what method is being used. To the right of each list item, there is a brief description of what the entity does.

When an item in this list is clicked, the interface will expand again to show information relevant to the selected

endpoint.

.18

API OVERVIEW GUIDE

Click on the endpoint GET /rest /users/me.

.19

API OVERVIEW GUIDE

Go over the details for this endpoint. In summary, it returns a JSON representation of the entity that is populated with

information that the access token represents. This information is tied to the current user. Once you've gone over the

information for the endpoint, click the Try it out! button.

In the Response Body section, there will be a JSON object of the users class, and it will contain the current user's

information.

.20

API OVERVIEW GUIDE

Creating API Requests

When making web requests to the API from your own application, make sure to include your token in the header for

your request. The steps for obtaining this token were outlined in the Prerequisites section of this documentation. This

section will outline how to include the token in your request from a third-party application.

Most modern web browsers either come with a set of developer tools (e.g., Chrome Developer Tools) or have a set that

can be found online (e.g., Firebug for Firefox). In the developer tools, there will generally be a Network tab that will

show all network calls being made through the browser. There are also a number of standalone software applications

that can be used to do this (e.g., Fiddler, Wireshark, Charles Proxy).

As an exercise, let's make the same request from the developer documentation we made in the last section, look at the

request using developer tools, and figure out where the token is used.

If you open up your developer tools and execute the same endpoint that we did before, you will see that the browser

sends out request with the following header.

The most important part of this header for our purposes is the Authorization field, which contains the word "Bearer"

followed by a space, followed by your token string. The word "Bearer" describes the type of token we are using for

authentication. This is the exact format the authorization field in the request headers should be in order to perform this

request successfully. Specifically, it should read exactly like:

Authorization: Bearer <token string>

Where <token string> is replaced with the actual token string.

.21

API OVERVIEW GUIDE

Using API Requests

Before moving onto the next exercise, let's dig into the response of the request we just made. There are a couple of

important things to highlight. If you look at the response header, you will see a field called X-Accellion-Location, which

indicates what object is being acted upon.

NOTE: In the case of an error, this field might not indicate the object being acted upon. Please consult our error-

handling documentation for those cases.)

For instance, this is the response header for the request we just made.

As you can see, the object being acted upon is the current user. In this case, the information about this user is just

being returned. However, when adding, removing, updating, or otherwise editing objects, it is often critical to make

note of which object is being acted upon.

The response of the request is the JSON object that we previously saw in the UI of the developer documentation page.

Here, it is important to note that every object has an id element, which is the unique identifier for the object with

respect to all other objects of that entity type. Most of the endpoints that get and/or modify a specific data will require

the id of the object that corresponds to the data. Such an endpoint will be outlined in the next section, as well as how

to obtain the id value for the request.

.22

API OVERVIEW GUIDE

Using id

Now that you can make requests using our API to get data from kiteworks, let's try another request that uses an id to

uniquely identify the object you want to get. Specifically, let's try to get a folder object that represents the My Folder

folder for the current user.

Unlike the users entity, which has the aforementioned endpoint to return the current user's information, the folders

entity does not have an endpoint to return the current user's My Folder folder. The general endpoint for getting folders

visible to the current user will have to be used, and the id of the folder must be given in the request to specify which

folder to get. If we look in the developer documentation, such an endpoint exists.

There are a number of ways to get the id of the My Folder folder for the current user, which I will outline here

currently.

One is simply to make the GET /users/me request. In the response of that request, there is a links array, in which there

is an element identified as syncdir. The id associated with that element is the id of the My Folder folder for this user.

.23

API OVERVIEW GUIDE

This method of obtaining the id is specific to the My Folder folder of the user, and it cannot be used to get the id of any

folder. A more general way to obtain the id of a folder is to navigate to that folder in the kiteworks UI. Once there,

observe the URL.

.24

API OVERVIEW GUIDE

The URL should read https://<hostname>/#/folder/ followed by a number. That number is the id of the folder that is

currently open.

While this will work for the majority of cases - folders being one of them, there are a few instances where there are not

available URLs to grab the id from. In those cases, the best way to get the id of a specific object would be to use the

corresponding endpoint that lists all instances of the class you are interested in. From the list, you can then pick which

instance is the one you are interested in, and from there, you can get the id.

Now that we have the id of the My Folder folder, we can plug it into the web request, and our response will be a JSON

payload that contains information relevant to that folder.

.25

API OVERVIEW GUIDE

Creating Objects

Now that we have been able to get the id of the My Folder folder and grab the associated JSON object, let's try to

actually create a folder inside of this one. This will, again, require the id of the folder, which we already have.

If you look at the developer documentation website, you will see that there is an endpoint under folders that is used to

create a new folder.

The parent id expected in this request is the id of the folder that we want to create our new folder in.

As a creation request for the API, this endpoint also requires some information for the object you wish to create. The

developer documentation outlines the format that this information should be provided in. This can be found under the

Data Type of the body parameter. In this case, a name is the only requirement. The required information is expected to

be in the Request Payload of the request. There are also options to add description and specify if the folder is

syncable. If these options are used, that information should also be included in the Request Payload.

Please note that the Request Payload is expected to be JSON and that the Content-Type must be application/json.

.26

API OVERVIEW GUIDE

Upon success, the response's header will look something like this.

The most noteworthy part of this response is the X-Accellion-Location field. This was mentioned before as an indicator

of which object is being acted upon. In the case of creating an object, this will be the new object that you have

created. This will also be a way to get the id of the object, for future use.

Now that we have created a folder, let us add one of your contacts as a downloader.

If you don't have any contacts or you wouldn't like to share this folder with any of your existing contacts, you can use

the POST /contacts endpoint under the contacts entity to create another contact.

.27

API OVERVIEW GUIDE

For this endpoint, you will need to supply a contact name and an email address. The Request Payload should look like

this.

Again, make note of the X-Accellion-Location field in the response header, where you can find the id for the contact

that was created. This id will be used in the next endpoint we use.

Use the GET /contacts/{id} endpoint, filling in the necessary id with the one we took from the last response header, to

get the information for this contact.

.28

API OVERVIEW GUIDE

Inside the response for this endpoint, there is an Items array, and the first element of that array contains a links array.

That array contains an element that has a field called entity with the value user. This indicates that the data in this

element corresponds to the user that is associated with this contact. Inside that element, there should also be an id

field. This is more clearly shown in the next figure.

The value of that id will be what we will use in our next web request's Request Payload.

Now that you have a contact that you would like to add to this folder, let's actually add him as a downloader. Under the

folders entity, there is a POST /folders/{id}/members entity. In the actual request, the id is the id of the folder you

want to add the user to. In this case, it would be the id of the folder we created earlier in My Folder.

.29

API OVERVIEW GUIDE

The Request Payload for this web request should contain both the userId for the contact you want to add (which we

obtained from the previous web request) and the roleId. A comprehensive list of every role and associated roleId can be

obtained through the GET /roles endpoint under the roles entity.

From the response of this web request, we can observe that a downloader's corresponding role Id is2.

The Request Payload should be formatted as follows.

After successfully performing this, you have created a folder and added a contact to it as a downloader. Now, this

contact has visibility into this folder and the ability to download files from it. In the next section, we will discuss how to

upload files to this folder via the kiteworks API.

.30

API OVERVIEW GUIDE

Adding Files

To add a file to the folder, we need to use the POST /folders/{id}/actions/file endpoint under the files entity.

Here, the id required in the web request is the id of the folder that the file should be added into. In this case, we could

grab the id indicated in the X-Accellion-Location field of the response header when we created the folder. The file also

needs to be attached, which is done via a multiple MIME request. Let's upload a text file with the classic "The Road Not

Taken" poem by Robert Frost.

.31

API OVERVIEW GUIDE

Again, the id of the new uploaded file can be found in the X-Accellion-Location field of the response header of this

request. Note this id, because we are going to use it to download this file in the next section.

Adding Large Files

The caller can request the APIs to upload or download any kind and size of file successfully under normal conditions.

kiteworks can also handle corner cases and report exceptions and errors logically.

Chunk Upload Workflow

Chunk Upload is aimed to let users upload large files by parts. This section briefly describes the workflow of a chunk

upload.

Chunk Upload Process Steps

Upload session initialization

The user can upload a new file to a folder or upload a new version of an existing file. To initiate a new file upload call:

POST /folders/{id}/actions/initiateUpload

{id} - Destination folder ID

To initiate a new file version upload call:

POST /files/{file_id}/actions/initiateUpload

{file_id} - ID of the file for the file version

If you call POST /folders/{id}/actions/initiateUpload with filename that already exists in this directory, the new version

of this file will be created.

.32

API OVERVIEW GUIDE

Request Body Parameters Description

filename (required) - Filename that will be created after upload session completion

totalSize (optional, required if totalChunks was sent) - File size in bytes

totalChunks (optional, required if totalSize was sent) - Amount of chunks that file is split to

Chunk upload supports two different workflows. The first one requires totalSize and totalChunks, the second one does

not require these fields, but it requires to send lastChunk field equals to 1 with the last chunk upload (see more details

below). The first workflow is preferable since server is able to validate total file content at the end of upload session.

1. To follow first workflow, send all fields listed above.

2. (SFTP Client) The second workflow is meant to be uses by the SFTP client. The SFTP client cannot know the

totalSize and totalChunks when an upload session is initiated. Send only the filename if you want to follow this

workflow.

If upload initialization was successful, response headers will contain "X-Accellion-Location" field with upload id value.

For example:

{ ..., "X-Accellion-Location": "http://homeurl.com/rest/uploads/1", ... }

Where 1 is an upload session ID. Use this ID to perform all further operations.

Retrieve Upload Session Data

After initialization each upload session will have assigned an "uri" parameter. This parameter contains uri where all

chunks for this upload session should be uploaded. To retrieve this parameter call:

GET /uploads/{id}

Response Body Parameters Description

userId - Upload session owner user ID.

timestamp - Upload session creation date.

totalSize - Total size of the file which was set in upload session initialization.

totalChunks - Amount of expected chunks amount, which was set in upload session initialization.

clientCookie - Client cookie field.

clientName - Client ID which is assigned to upload session owner.

svrUploadTime - Amount of time in milliseconds that was spent on uploading all uploaded file chunks.

error - Last error message of the chunk upload, if any.

completeOk - Boolean flag, equals to 0 if session is not completed (not all chunks was uploaded). Equals to 1 if upload

session is finished. But since upload session is deleted after successful finish, this parameter will always be equal to 0 if

upload session exists.

uri - Uri where all chunks for this upload session should be uploaded.

Format of the uri is {host_name}/rest/uploads/{id}.

Example: dacfs_upload1/rest/uploads/1.

dacfs_upload1 - is a host name.

1 - is an upload ID.

The host name parameter from the uri field is determined by the server according to user location settings. The host

may be remote or local. If there is any local host, the file will be saved at the local host. If there is no local host to

.33

API OVERVIEW GUIDE

upload, the file will be sent to available remote host.

Upload Chunks

After retrieving correct endpoint for the chunks upload (uri field), you can upload all file chunks starting from the first

one. To do so, call:

POST {host_name}/rest/uploads/{id}

Request Body Parameters Description

compressionMode (required, optional if lastChunk = 1) - Compression mode for the chunk content. Available and valid

modes:

NORMAL - file chunk content is uploaded without compression (as is)

GZIP - file chunk content is compressed using https://en.wikipedia.org/wiki/Gzip format

ZLIB - file chunk content is compressed using https://en.wikipedia.org/wiki/Zlib format

compressionSize (required, optional if lastChunk = 1) - File chunk content size in bytes after compression. If

compressionMode is set to NORMAL, then compressionSize should match with originalSize.

originalSize (required, optional if lastChunk = 1) - File chunk original size in bytes.

content (required, optional if lastChunk = 1) - File chunk content string that is converted into base64 string

https://en.wikipedia.org/wiki/Base64. User should encode the file content into base64 string after compression (if

there is any compression applied), not before.

lastChunk (optional, 1 or 0 value) - This field allows to mark current chunk as the last one and finish upload session. It

can be used only for the second workflow (SFTP Client). If the user initiated upload following SFTP Client workflow and

sending this field equal to 1 and content field is not empty, then all fields from above (compressionMode,

compressionSize, originalSize, content, lastChunk) will be optional.

Upload all chunks starting from the first one. After successful uploading the first chunk the user should receive the 200

response code. After uploading the last chunk the user should receive the 201 response code and the created file ID in

a response header field "X-Accellion-Location". For example:

{ ..., "X-Accellion-Location": "http://homeurl.com/rest/files/1", ... }

Where 1 - is a file ID.

Depending on what workflow you chose at the upload initialization, the chunk upload workflow can be different:

1. If totalSize and totalChunks was sent, the upload session will be finished automatically after the last chunk is

be uploaded. For example, if totalChunks = 4, then server will accept the fourth chunk as the last one and will

finish the upload session. If totalChunks was set in upload initialization, this upload session cannot be finished

by sending the chunk with lastChunk = 1.

2. (For the SFTP Client) If totalSize and totalChunks was not sent, the upload session will be finished only if user

send the chunk with lastChunk = 1. The server will accept this chunk as the last one and will finish the upload

session. For this last chunk the server will not perform content validation.

Important Note: Despite the fact that if lastChunk = 1 then all other chunk fields became optional, if user sends content

with some value and lastChunk = 1, the server will validate this chunk content and all other fields

(compressionMode, compressionSize, originalSize) will be required and validated.

.34

API OVERVIEW GUIDE

Terminating Upload Session

The user can terminate the upload session by calling:

DELETE /uploads/{id}

NOTES

Chunk upload requests requires data transformation, that can hardly be done without code help (split file into chunks,

encode file content, create content fingerprint, etc.). The following php script is an example that will generate all

needed data for whole chunk upload process for the NORMAL compress mode. The script will generate data for 4

chunks. The script may be upgraded to support different compression modes and chunks amount.

Generate_chunks_data.php – Download <?php

class ChunkGenerator

{

const COMPRESSION_NORMAL = 'NORMAL';

const COMPRESSION_GZIP = 'GZIP';

const COMPRESSION_ZLIB = 'ZLIB';

public $validCompression = [

self::COMPRESSION_NORMAL,

self::COMPRESSION_GZIP,

self::COMPRESSION_ZLIB

];

/**

* Create test file data

*

* @param int $totalChunks

* @param string $compressionMode

* @return array

*/

public function initiateFileData($compressionMode = self::COMPRESSION_NORMAL,

$totalChunks = 4)

{

$fileData = [];

$fileData['filename'] = uniqid() . '_test_file.txt';

$fileData['content'] = $this->generateRandomString();

$fileData['totalChunks'] = $totalChunks;

$fileData['clientCookie'] = $fileData['filename'];

$fileData = $this->splitFileIntoChunks($fileData, $compressionMode);

unset($fileData['content']); // We don't need this for the qa

return $fileData;

}

/**

* Split file content into chunks

*

* @param array $fileData

* @param string $compressionMode

.35

API OVERVIEW GUIDE

* @return mixed

*/

public function splitFileIntoChunks($fileData, $compressionMode)

{

$fileData['totalSize'] = strlen($fileData['content']);

$fileData['mimeType'] = 'text/plain';

$fileData['timestamp'] = time();

$fileData['fingerprint'] = md5($fileData['content']);

$chunkSize = ceil($fileData['totalSize'] / $fileData['totalChunks']);

$split = chunk_split($fileData['content'], $chunkSize);

$chunksContent = explode("\r\n", $split);

$fileData['chunks'] = [];

foreach ($chunksContent as $i => $originalContent) {

if (!empty($originalContent)) {

$compressedContent = $originalContent;

switch ($compressionMode) {

case self::COMPRESSION_NORMAL:

break;

case self::COMPRESSION_GZIP:

$compressedContent = gzencode($originalContent);

break;

case self::COMPRESSION_ZLIB:

$compressedContent = gzcompress($originalContent);

break;

}

$fileData['chunks'][$i]['index'] = $i;

$fileData['chunks'][$i]['originalSize'] = strlen($originalContent);

$fileData['chunks'][$i]['fingerprint'] = md5($originalContent);

$fileData['chunks'][$i]['content'] =

base64_encode($compressedContent);

$fileData['chunks'][$i]['compressionMode'] = $compressionMode;

$fileData['chunks'][$i]['compressionSize'] = strlen($compressedContent);

} else {

unset($fileData['chunks'][$i]);

}

}

return $fileData;

}

public function generateRandomString($repeat = 100)

{

return str_repeat(md5(time()), $repeat);

}

}

$chunkGenerator = new ChunkGenerator();

$fileData = $chunkGenerator->initiateFileData();

print_r($fileData);

.36

API OVERVIEW GUIDE

To launch this script, launch terminal, navigate to a folder where this script is located and execute this command:

“php generate_chunks_data.php”

The script will display all the data in your terminal window.

Downloading Files

Note: Files that are not text files will have a garbled response when downloaded using the developer documentation

page. Files are not downloaded directly to the file system, as this is for testing the endpoints in this self-contained area.

Now, let's try downloading the file we just uploaded using the GET /files/{id}/content endpoint under the files entity.

.37

API OVERVIEW GUIDE

The first id needed for this web request is the id of the file to be downloaded, which we noted at the end of the

last section. Once the web request returns, your response should be the Robert Frost poem we added.

.38

API OVERVIEW GUIDE

Enabling the kiteworks API Playground UI

The following steps help you get started with the kiteworks API Playground. Exploring using kiteworks APIs requires development experience.

1. On the Application page, click on Custom Applications under Client Management.

2. The Enable kiteworks API Playground UI switch should be ON. If the switch is turned off, click on the switch to turn it ON.

3. To view the complete list of APIs, click Developer Documentation located under the Help (?) icon of the kiteworks Admin console as shown below.

The Developer Documentation page displays with the listing the library of APIs as shown below.

.39

API OVERVIEW GUIDE

.40

API OVERVIEW GUIDE

Customizing Settings, Scopes and Security

Select the Application Name you just created, and customize the Settings, Scopes, and Security.

Settings

You can make changes to the settings, if desired.

.41

API OVERVIEW GUIDE

Scopes

Select the APIs you plan to use for your custom application. By default, all APIs are selected when you first create the application.

Security

Remote Wipe Enabled:

Enable Remote Wipe for this application.

Pin Enabled:

Specify whether a PIN should be enabled for this application. Recommended for mobile apps.

White Listed Apps:

List third-party mobile apps that can be used to open files via the Open-In menu.

.42

API OVERVIEW GUIDE

Select Save Changes to save your changes.

You are now ready to test your app. Go to https://%%HOST%%/oauth_callback.php /rest/index.html to test your app using the app credentials.

Note “your kiteworks hostname” is the name of your kiteworks deployment.

.43

API OVERVIEW GUIDE

APIs Overview

kiteworks APIs provide broad coverage of the platform. The APIs can be categorized into Content, Collaboration, Preferences, Contacts, Security, Clients, and kiteworks Maintenance APIs.

Content APIs

Content-related APIs provide access to user content in your application. You will be able to access and manage files and folders as a part of the business flows of your app and work with files from various enterprise content sources like Microsoft SharePoint or EMC Documentum.

users

users APIs enable your application to obtain basic information about the user, user's root folders, and provide a starting point to further navigate through the files and folders the user has access to. By using the /users/me endpoint, you can obtain the ID of the user, the IDs of the root folder for this user, the email address or the name of the user, and status of the user (active, deleted).

Complete details of the users API is available at <your installation URL>/rest/index.html#!/users.

folders

The next step is to work with the files and folders accessible to the authenticated user.

Complete details of the folder API is available at <your installation URL>/rest/index.html#!/folders.

files

Together with folders, files are another fundamental entity that your application will have at its

disposal. Complete details of the files API is available at <your installation URL>/rest/index.html#!/files.

sources

One of the advantages of the kiteworks Mobile Content Platform is its ability to securely connect to existing enterprise content sources through a single user interface. Using the sources APIs, your application can access and manage EC content sources in a similar fashion.

Complete details of the sources API is available at <your installation URL>/rest/index.html#!/sources.

trays The Move Tray is a powerful tool that allows end users to collect references to files they have access to, and later on copy or move them to a different folder, or mail them to other users.

Complete details of the trays API is available at <your installation URL>/rest/index.html#!/trays.

.44

API OVERVIEW GUIDE

Collaboration APIs

The collaboration-related APIs are intended to provide your application with the powerful collaboration tools that users have in kiteworks. In addition to being able to invite users to shared folders, these APIs allow users to collaborate on files and folders, construct and receive mail, add comments, and assign tasks.

mail

The mail APIs allow you to access emails sent and received on behalf of the user authenticated through your application.

Complete details of the mail API is available at <your installation URL>/rest/index.html#!/mail.

comments

In addition to comments-related endpoints in /files, the /comments/ endpoints allow you direct access to existing comments for update and delete actions.

Complete details of the comments API is available at <your installation URL>/rest/index.html#!/comments.

tasks

Similar to the /comments endpoint, the /tasks/ endpoints allow you direct access to existing tasks for update and delete actions.

Complete details of the tasks API is available at <your installation URL>/rest/index.html#!/tasks.

.45

API OVERVIEW GUIDE

Preferences APIs

kiteworks Mobile Content Management platform provides a set of APIs for preferences-related entities: folder notifications, favorite folders, languages, and time zones.

notifications

The notifications entity endpoints allow the management of notification settings for important folders in the system for the given user.

Complete details of the notifications API is available at <your installation URL>/rest/index.html#!/notifications.

favorites

The favorites entity endpoints enable your application to manage the favorite folders for the authenticated

user. Complete details of the favorites API is available at <your installation URL>/rest/index.html#!/favorites.

languages

The languages APIs provide your application with the ability to retrieve the languages supported by the kiteworks system.

Complete details of the languages API is available at <your installation URL>/rest/index.html#!/languages.

timezones

The timezones APIs enable your application with the ability to list all the time zones supported in the system, and get the details about the time zones, like the name and time offset.

Complete details of the timezones API is available at <your installation URL>/rest/index.html#!/timezones.

Contacts APIs

contacts

The contacts APIs provide your application with the ability to manage the user contacts.

Complete details of the contacts API is available at <your installation URL>/rest/index.html#!/contacts.

groups

kiteworks provides end users with the ability to define personal contact groups. Personal groups can be used for allowing access to a folder, or for sending mail. Complete details of the groups API is available at <your installation URL>/rest/index.html#!/groups.

LDAP Groups

If your installation is integrated with LDAP, Administrators can enable LDAP groups to be available to end users when sharing folders. Your application will be able to add, update, or remove LDAP groups that are available to end users by utilizing the /ldapGroups/ endpoints.

.46

API OVERVIEW GUIDE

Complete details of the ldapGroups API is available at <your installation URL>/rest/index.html#!/ldapGroups.

Security APIs

profiles

The /profiles/ endpoints allow your application to manage the privileges assigned to kiteworks users. Your application can identify the list of User Profiles in the system and inspect the features and settings associated with each User Profile.

Complete details of the profiles API is available at <your installation URL>/rest/index.html#!/profiles.

roles

The roles APIs allow you to get the details of folder roles in the system.

Complete details of the ldapGroups API is available at <your installation URL>/rest/index.html#!/ldapGroups.

adminRoles

The adminRoles APIs allow your application to manage the assignment of Administrator roles to users.

Note In order to use the adminRoles APIs your application will need to authenticate with an Administrator user.

Additionally, only System Administrator can promote a user to System Administrator, Application Administrator. User cannot self-promote to System Administrator.

Complete details of the adminRoles API is available at <your installation URL>/rest/index.html#!/adminRoles.

devices

Users may access kiteworks from various devices: mobile phones, tablets, etc. Device endpoints can be used to track access of individual devices to user accounts, and perform remote wipe on any device.

Complete details of the devices API is available at <your installation URL>/rest/index.html#!/devices.

admin

The admin APIs allow your application to perform administrative actions on many entities that exist in the system. The endpoints are very similar to the endpoints of the actual entities, the difference is that your application will need to authenticate with an Administrator user in order to perform the calls.

• Client Applications: using /admin/clients/ endpoints, you can create and configure the configuration

settings of the client applications registered with kiteworks, and list API Scopes available. • Devices: using /admin/devices/ endpoints you can find the list of user devices that are allowed to

connect to kiteworks, log their access to the platform, and update, or remove them as necessary • LDAP Groups: List, create or delete LDAP groups in the system

• License: Upload a new kiteworks license • Locations: List, create, or delete kiteworks Locations: requires System Administrator, and is applicable

.47

API OVERVIEW GUIDE

for on-premises Enterprise and Enterprise Connect Packages only • Profiles: List user Profiles. For details on profiles please refer to kiteworks Administration Guide

• Sources: List, add, update, remove Enterprise Connect sources

• Users: List, add, update, delete users, user settings, admin roles, profile image.

Complete details of the admin API is available at <your installation URL>/rest/index.html#!/admin.

Client Management APIs

clients Using the clients APIs, you can register a new application, and manage the configurations for the applications allowed to connect to kiteworks.

Complete details of the clients API is available at <your installation URL>/rest/index.html#!/clients.

scopes

One of the main security and safety mechanisms for preventing unauthorized or accidental application use of the platform resources is the Administrator ability to set the API scopes for each application. kiteworks Mobile Content Platform provides the /scopes endpoint that allows applications to determine the APIs supported by the platform, so the application can properly construct the API calls to the platform.

Complete details of the scopes API is available at <your installation URL>/rest/index.html#!/scopes.

kiteworks Maintenance APIs

licenses If your application is in charge of updating the license of your kiteworks installation it can use the /licenses endpoint to upload a new license. Complete details of the licenses API is available at <your installation URL>/rest/index.html#!/licenses.