API OVERVIEW GUI DE - accellion.com · API OVERVIEW GUIDE Table of Contents ... agents and...
Transcript of API OVERVIEW GUI DE - accellion.com · API OVERVIEW GUIDE Table of Contents ... agents and...
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 [email protected] 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
spaceseparated 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.
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.