Introduction

The sandbox is an environment that allows developers to quickly explore and experiment with the Xillio API. The sandbox connects to public cloud storage that is automatically scratched every hour. This means that as a developer experimenting you cannot break the sandbox. It resets itself every hour.

To get access you need to register for the sandbox.

The sandbox is public and shared with everybody. This means that as a developer you should be careful with the content that you upload. That content is visible to all users of the sandbox. Make sure that you do not upload sensitive or confidential materials.This document helps you get started with your experiments and exploration of the sandbox. Please also take a look at the Xillio API documentation at https://docs.xill.io and the FAQ on our support site for more information.

Throughout this document, we will reference the documentation where you can find background information or a full description of all the parameters and options for a call. The Xillio API is a REST API that uses JSON. This means that in order to use the API you need to do HTTP calls. This document assumes that you have a basic understanding of the HTTP protocol, REST principles, and JSON format.

In a lot of cases, HTTP calls can be done via your browser, however, to protect the content stored in the repositories accessed via the Xillio API we use OAUTH2 authentication. This makes it difficult to use a browser to make the appropriate HTTP calls. This document and the documentation provide examples and calls using the curl command line tool which is available for many different platforms. You can, of course, use other tools, such as Postman or a programming language of choice instead. In most cases, this should be straightforward. Please contact us if you run into any problems.

Your first interaction with the Xillio API sandbox

For your first interaction with the Xillio API we will simply use your browser and call the ping endpoint:

  • Open your browser
  • Go to: 
    https://sandbox.xill.io/v2/system/ping
  • You should see the following response in your browser:
    {
    "tenant" : "sandbox",
    "serverTime" : "2018-07-31T12:18:56.819Z"
}

The ping endpoint is an easy way to verify whether you can reach the Xillio API from your computer. This call does not require authentication or authorization and can therefore be easily executed in your browser.

Alternatively, you can use curl:

  • Open a terminal or command line window.
  • Run the command:
    curl -X GET https://sandbox.xill.io/v2/system/ping
  • You should see the following response:
    {
    "tenant" : "sandbox",
    "serverTime" : "2018-07-31T12:18:56.819Z"
}

You can optionally add the -i flag to the curl command. This flag will cause curl to also show all HTTP response headers:

  • Open a command line window.
  • Run the command: 
    curl -X GET https://sandbox.xill.io/v2/system/ping -i
  • You should get the following response:
    HTTP/1.1 200
Server: nginx/1.15.2
Date: Tue, 31 Jul 2018 12:22:57 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Access-Control-Allow-Origin: *

{
  "tenant" : "sandbox",
  "serverTime" : "2018-07-31T12:22:57.983Z"
}

The values in the header might be different from the values that you are seeing, e.g. the Date header will, of course, show the current date and time when you execute the call. We will leave out the -i flag in the remainder of this document, but you can add it to every curl call if you want to observe the HTTP response headers.

Getting an authentication token for the Xillio API

The next step to use the Xillio API is to request an authentication token. In order to retrieve an authentication token, you will need the username and password that you've received for the sandbox.

  • Open a command line window.
  • Run the command: 
    curl https://sandbox.xill.io/oauth/token \
  -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  -d "grant_type=password&username=<username>&password=<password>&client_id=app"

    Make sure to replace <username> and <password> with the values supplied to you, e.g.

    curl https://sandbox.xill.io/oauth/token \
  -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  -d "grant_type=password&username=john-doe&password=p455w0rd&client_id=app"

            NOTE: <username> and <password> need to be URL encoded when using curl.

  • You should get the following response:
    {
  "access_token" : "*****",
  "token_type" : "bearer",
  "expires_in" : 43200,
  "scope" : "user users configurations entities contents",
  "jti" : "79a977b7-c887-4617-8d76-342abfc8a5bd"
}

Instead of the five asterisks in the access_token field, you will see a long seemingly random string that represents an access token that you need to do any additional calls to the API. You can ignore all the other fields for now. The access tokens expire, when that happens you can simply execute a new token request using the curl command above to obtain a new, fresh access token.

Getting a list of configured repositories from the Xillio API

Within the Xillio API, you can configure multiple repositories. In these configurations, you specify the connection parameters that you need to connect to your repositories. The sandbox contains a number of pre-configured repositories. These repositories connect to cloud storage that is automatically scratched every hour. You can not add, edit or delete configurations from the sandbox.

In order to get the list of repositories, we will use a GET call on the entities endpoint.

  • Copy the value of the access_token from the previous response without the surrounding quotes.
  • Run the curl GET command below where you replace the five asterisks ***** with the copied access token: 
    
curl -X GET https://sandbox.xill.io/v2/entities?scope=children \
  -H "Authorization: Bearer *****"

    The -H flag tells curl that you want to add a request header to the HTTP request. In this case, the header contains the authorization information stored in the access token. Any additional curl calls that you make need to include this -H "Authorization: Bearer *****" command line flag.

  • You should get the following response on the above call: 
    
{
  "children" : [ {
    "id" : "https://sandbox.xill.io/v2/entities/5a184d0207903113023b5aa8",
    "xdip" : "xdip://5a184d0207903113023b5aa8/",
    "kind" : "FileSystem",
    "original" : {
      "name" : {
        "systemName" : "5a184d0207903113023b5aa8",
        "displayName" : "Sandbox Folder #1"
      }
    },
    "modified" : {
      "name" : {
        "systemName" : "5a184d0207903113023b5aa8",
        "displayName" : "Sandbox Folder #1"
      }
    }
  }, {
    "id" : "https://sandbox.xill.io/v2/entities/5a184d0207903113023b5aa9",
    "xdip" : "xdip://5a184d0207903113023b5aa9/",
    "kind" : "FileSystem",

   ... truncated for readability ...
  
  } ]
}

    The above response contains a children field which contains an array of configured repositories. The id field of every repository contains a valid URL that you can use to browse that repository. Please note that the actual id values and URL might differ from what you are seeing in your responses.

Continue to browse the repositories

You can navigate content with the Xillio API by doing get calls, using the id fields of entities, such as the repositories retrieved in the example above.

  • Do a GET call using curl on one of the ids retrieved above. Do not forget to include the -H flag. E.g.: 
    curl -X GET https://sandbox.xill.io/v2/entities/5a184d0207903113023b5aa8?scope=children \
  -H "Authorization: Bearer *****"

From here you can continue to retrieve additional folders and entities.

Next steps

The Xillio API can be used to retrieve metadata about entities and entity content stored in repositories. With the steps above we have barely touched the surface of what the Xillio API can do for you. Please read the documentation and do some more experiments in the sandbox. That's what it's there for, e.g.:

We also encourage you to use your own programming language and tool stack to do the calls above that we did on the command line using curl.