About this document

We'd like to give you a quick introduction to the integration of DRACOON into your own software. Further details about our API are provided in further pages.

JSON REST API

DRACOON provides an extensive JSON/REST API. If you are not familiar with the JavaScript Object Notation (JSON) or REST APIs, please take a closer look at these concepts before advancing here.

As our client applications (DRACOON Web App, DRACOON for Android/iOS/Windows/Mac/Outlook, etc.) also use solely DRACOON's public API, as we provide 100% of all features in these interfaces. That means that you are able to do anything with DRACOON that is currently implemented.

Community board

When you are integrating the DRACOON API in any of your software, we strongly recommend that you subscribe to our community board where we can easily provide you with updates about upcoming API changes and other important information as well as where you can exchange ideas and pose questions regarding API integrations.

Swagger

Swagger is a very powerful API framework that we use for many things – one of them is providing a very intuitive documentation with an interactive web client for the API. You can find it at the following URL: https://dracoon.team/api/. We suggest that you open up that page before reading any further.

What you need

There are some more things you should keep at hand to be able to test all the following examples by yourself.

First of all, you should have a valid DRACOON account. If you do not already have one, you can sign up for a free account here: https://www.dracoon.com/service/free-trial/.

Since we provide you with the Swagger UI, you do not necessarily need an HTTP client. However, if you want to try your first script, you will need a client that is able to connect over HTTPs. A JSON parser might help you in generating and parsing JSON structures that are used in the requests and responses – but is also not necessarily required.

First steps

Retrieving the version numbers of the system

As a first test we try the call GET /public/software/version that will inform us about the currently installed software versions on the system. You can very easily try this call by looking it up in the Swagger UI, expanding its view and clicking on the button "Try it out!". The following screen shot shows a possible response.

As you might have noticed, this request does not require any parameters. The complete request URL is shown in the first part of the extended pane, followed by the response body, the response code and the response header. The latter might only be of interest to you in certain cases. The response code is always a standard HTTP Status Code and tells you whether the request was processed successfully (2xx) or what went wrong (invalid request: 4xx, issue on server-side: 5xx). You should never retrieve an internal server error (500); however if you do, you discovered a nasty bug and we are politely asking you to provide us with information about what you did and how so we can fix the issue.

In cases where you receive a client error (4xx) we provide further details in the response body where you will not receive the expected JSON structure but our default error structure with additional error codes to identify the problem and a human readable version of the error to provide you with further information. All possible errors are (together with their error codes) documented in the Swagger Documentation.

If everything turned out well (response code 2xx), the response body contains your requested JSON structure with your data. In our first case, you should receive something similar to this:

{
  "restApiVersion": "4.5.0",
  "sdsServerVersion": "4.5.0",
  "buildDate": "2018-02-07T10:34:43Z"
}

Congratulations, you just completed your first communication with the DRACOON API!

As an additional help, we will provide you with code examples in different programming and scripting languages. Here's one for our first API call in Ruby:

# We import some gems that make our life easy :)
require 'json'
require 'rest_client'
 
# We define host, path and api we'd like to call
host = "https://dracoon.team/"
path = "api/v4"
api = "/public/software/version"
 
begin
  # This sends a request to the defined URL and stores the response.
  response = RestClient.get "#{host}#{path}#{api}", {:accept => :json}
rescue
  # That would print the error message in case something went wrong
  puts $!
end
 
# We parse the JSON structure into an associative array
versions = JSON.parse(response)
 
# Print the contents of the array on the console
puts versions

 

Logging onto DRACOON

Well, that first API call was very easy – we didn't have to send any parameters or modify header information. However, we need these further information in additional calls where authentication is required and where complex parameters have to be provided. But first things first – let's log on with an existing user so we can access protected ressources and interact with data rooms and files.

Logging on is one of several workflows we defined. You can access a detailed documentation about several more here.

Workflow means that a number of consecutive API calls are necessary to achieve a certain goal – in our case, logging on a user. However, the log-on workflow is pretty simple and consists of only two API calls:

1. GET /auth/ressources
2. POST /auth/login

The first call provides us with some information about parameters we will set in the second call. So let's start.

The call GET /auth/ressources is as simple as GET /public/software/version – we do not need any parameters or authentication so let's simply call it. The response should similar to the following JSON structure:

{
  "languages": [
    {
      "languageId": 1,
      "description": "Deutsch",
      "isoCode": "de"
    },
    {
      "languageId": 2,
      "description": "English",
      "isoCode": "en"
    },
    {
      "languageId": 3,
      "description": "Español",
      "isoCode": "es"
    },
    {
      "languageId": 7,
      "description": "Français",
      "isoCode": "fr"
    }
  ],
  "authTypes": [
    {
      "key": "1",
      "value": "sql"
    }
  ]
}

As you can see, we receive an array of languages and one of auth types. The first one contains all the supported languages and the second one contains all possible authentication methods. "SQL" simply means a local login with user name and password; alternatives might be Active Directory, RADIUS etc.

So let us now take a closer look at the second call in our workflow: POST /auth/login.

As you can see in Swagger Documentation in the Parameters section, the request body should contain a JSON structure that looks like this:

{
  "login": "",
  "password": "",
  "token": "",
  "language": "",
  "authType": ""
}

Those fields are not always self-explaining, so let's take a closer look at the Swagger Documentation. By clicking on the word "Model" above that box we get detail information on the attributes:

As you can see, only the fields login and password are mandatory, the others are optional. Let's ignore the optional attributes for now and just create a request with the mandatory attributes.

So we need to create a request body with a JSON structure that contains the mandatory fields filled with reasonable values. login contains the login email address and password should not require any explanations. Even though the attribute authType is optional, we strongly recommend that you provide this attribute in your login requests. The complete request body should look like this:

{
  "login": "my.user@dracoon.com",
  "password": "Sup3rS3cr3tP@ssword",
  "authType": "sql"
}

You can easily test your requests by using Swagger UI and simply submitting your JSON structure as request body.

Once again, a JSON structure is provided as response body that should – if everything worked out ok – contain only one value: The token which is an Authentication Token that represents your user session on DRACOON and which is necessary to access protected ressources. If you want to end your session, you can call POST /user/logout at any time.

To verify that the log-on worked, we could now call a protected ressource and should receive a proper response. For example purposes we could use GET /user/account that returns information about the currently logged on user.

The Swagger Documentation shows another request parameter that is not the body: We need an authentication header called X-Sds-Auth-Token. As fate would have it, that is exactly the token we just received as response of POST /auth/login. Swagger UI makes it relatively easy for us to set this header; we simply have to copy the token from the previous response into the correct field. After submitting that call we should see a JSON structure as response body that represents the current user. Great – everything worked and we are good to go.

Here's a Ruby script that invokes the three described API calls:

# We import some gems that make our life easy :)
require 'json'
require 'rest_client'
 
# We define host, path and api we'd like to call
host = "https://dracoon.team/"
path = "api/v4"
 
# User credentials
user = "my.user@dracoon.com"
password = "Sup3rS3cr3tP@ssword"
 
 
# POST /auth/login
begin
  # This sends a request to the defined URL with a certain content-type and stores the response.
  api = "/auth/login"
  response = RestClient.post "#{host}#{path}#{api}", { 'login' => user, 'password' => password, 'authType' => 'sql'}.to_json, {:content_type => :json, :accept => :json}
   
rescue
  # That would print the error message in case something went wrong
  puts $!
end
 
# We parse the JSON structure into an associative array
token = JSON.parse(response)["token"]
 
 
# GET /user/account
begin
  # This sends a request to the defined URL with a certain content-type and stores the response.
  api = "/user/account"
  response = RestClient.get "#{host}#{path}#{api}", {:accept => :json, 'X-Sds-Auth-Token' => token}
   
rescue
  # That would print the error message in case something went wrong
  puts $!
end
 
# We parse the JSON structure into an associative array
user = JSON.parse(response)
 
# Print the first name and last name on the console
puts user["firstName"] + " " + user["lastName"]
  
 
#Finally, we should log off to destroy the token
 
# POST /user/logout
begin
  # This sends a request to the defined URL with a certain content-type and stores the response.
  api = "/user/logout"
  response = RestClient.post "#{host}#{path}#{api}", {}, {:accept => :json, 'X-Sds-Auth-Token' => token}
 
rescue
  # That would print the error message in case something went wrong
  puts $!
end
 
 
if response.code == 200
  puts "Successfully logged off."
else
  puts "Something went wrong during log off. :("
end

 

How to move on

Now that you've learned the basics you should go out and explore our API. We invite you to check out the other documents in this section as well for detailed information about our workflows, about crypto usage and you might want to download one of our Software Development Kits.