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 additional articles.

JSON REST API

DRACOON provides an extensive JSON/REST API. If you are unfamiliar with 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 DRACOON's public API solely, we provide 100 % of all features in these interfaces. That means that you also can, via the API, 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 post questions regarding API integrations.

Swagger

Swagger is a very powerful API framework that we use for many things—one of them is providing very intuitive documentation with an interactive web client for the API. You can find it under the /api/ URI, such as https://dracoon.team/api/ (here, dracoon.team is just an example of a DRACOON environment, which you can replace with your own environment). 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 generate and parse JSON structures that are used in the requests and responses—but it 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 easily try this call by looking it up in the Swagger UI, expanding its view, and clicking the "Try it out!" button. The following screenshot 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 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 this 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 resources and interact with data rooms and files.

DRACOON uses the OAuth 2.0 protocol for authentication and authorization. OAuth 2.0 is an open standard and widely used authorization protocol.

Using Swagger, simply click Authorize and follow the instructions.

This will authorize Swagger UI to make API calls on your behalf. Technically, Swagger UI received an access token and will send it along with subsequent requests.

If you want to register a custom client (a PowerShell script, for example) to call the API, please refer to this blog post that contains detailed instructions.

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 articles 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 (SDKs).