qxhub AG API Documentation

Getting Started

The qxhub API lets you integrate qxhub with other applications or services.

Base URL

Please use https://api.qxhub.net as the Base URL address for accessing our API services. It represents the starting point for all API endpoints and serves as the foundation upon which requests are made. To interact with our API, you will need to prefix each endpoint with this Base URL.

Security and Authentication

You must be a verified user to make API requests. You can authorize against our API with an Access Token. The Access Token is created and delivered when you log in to our services. Authentication is then possible in two ways: If the request contains the session cookies of a logged in qxhub session, then the user and permissions of that session are used. This is particularly comfortable when testing our API in a web browser, because then requests are automatically authenticated if qxhub is used in another tab. In order to connect to our API from outside a web browser or without session cookies, the Access Token must be provided in the Authentication-Header if each Http-Request. To get a valid Access Token, initiate a call to https://api.qxhub.net/core/api/OAuth/Authorize and include your credentials. In case of a successful authorization, you are provided with a newly generated Access Token. Treat this token like a password.

To increase the security, each Access Token has a limited Time To Live (TTL). As soon as the Access Token expires, it can no longer be used to authenticate against our API. So that you do not need to provide new user credentials to qxhub, we also deliver a Refresh Token with every successfully created AccessToken. The Refresh Token can then be used, to automatically create a new valid Access Token without the need of an additional login process. To do so, you can call the https://api.qxhub.net/core/api/OAuth/Authorize endpoint, again, and provide the Refresh Token.

Http Request Headers

This API exclusively accepts JSON data. Ensure to always include a 'Content-Type: application/json' header when performing PUT or POST operations. Additionally, always set the 'Accept: application/json' header to your requests, if not stated otherwise.

Headers
Content-Type: application/json
Accept: application/json

JSON

If not stated otherwise, we accept and respond with data serialized in JSON format. In our responses, null values are serialized as 'null'. However, when you send data to our API, it is not necessary to include properties whose value is null. All properties that are missing from the JSON object but are expected are assumed to be null.

For further information on how different data types are serialized, check the table below.

Type Representation in JSON
boolean Serialized as true/false.
string Serialized as JSON string, empty strings are intepreted as null.
integer Integer numbers (that can safely be represented as a double) are serialized as JSON numbers.
float/double Serialized as JSON numbers.
date and timestamp Serialized in ISO8601 format, always use UTC time zone
enum Sometimes a property value can be one of a fixed number of named options. Those are then serialized as JSON string with the name of the option.

Change Policy

Our API is continuously being developed and improved, but we are still trying to keep it as stable as possible. We try to only have changes that are backwards compatible: usually the changes are only additions, e.g. new resources are implemented or new properties are added to existing resources. Sometimes breaking changes cannot be avoiced, e.g. when a new features requires an incompatible change to the underlying data model, all those changes will be documented in the change log. In some rare cases, it is possible that a property is removed from the API documentation or exchanged by another property. To be compatible with older versions, those properties are only removed from the API documentation but are still being evaluated.

qxhub may modify the attributes and resources available to the API and our policies related to access and use of the API from time to time without advance notice. qxhub will use commercially reasonable efforts to notify you of any modifications to the API. Modification of the API may have an adverse effect on connected Applications, including but not limited to changing the manner in which Applications communicate with the API and display or transmit Your Data. qxhub will not be liable to you or any third party for such modifications or any adverse effects resulting from such modifications.

API error reference

qxhub API errors come with 'Content-Type: application/json'.

Error JSON structure

Property Datatype Description
type string Reference that identifies the problem type. Can be used to technically distinguish individual types of errors.
title string A short, human-readable summary of the problem type. It should not change from occurence to occurence of the same problem.
status integer The HTTP status code, generated by the origin server for this occurence of the problem.
message string A human-readable explanation specific to this occurence of the problem. This ight be replaced by some generic information if the detail information would be security sensitive.