DE EN EN (Google)

easydb API

The easydb server offers a RESTful API over HTTP. Almost all operations require a session token, which can be acquired and authenticated with /api/v1/session.

This token is necessary to identify the authenticated session.

The token can be passed in the query string as the URL parameter token, as well as the HTTP header x-easydb-token. The server will always try to identify the session by looking for a token, provided in any of these ways.

HTTP Request

Unless otherwise stated, all API calls use the following structure:

The HTTP Content-Type must be set according to the input given:

HTTP Response

The server will sometimes provide output data in the HTTP Response. Unless stated otherwise, the output format is JSON. The server will set the HTTP Response Content-Type accordingly.

There are three types of responses:

Reponse Type HTTP status code Description
Success 200 The request was successful. The data format is described in the “Output” section of the API call
Partial 202 The request was partially successful. More information and/or actions from the user are required. These kind of responses can be found in the section Confirmation responses
Error 400 / 500 The request was unsuccessful. The errors are described in the section Errors. A status code of 500 is an internal server error; 400 means an expected error occurred

The section “HTTP status codes” of each API call contains a description of the possible responses.

The server always returns the following response headers:

Cache handling

For GET requests, there is some common behaviour for all APIs. The only exception are plugin-defined APIs (/api/v1/plugin/…), in these cases it’s up to the plugin to define the behaviour.

When the cache_seconds request parameter is present and its value is above 0, private caching is allowed for the given period by setting the Expires (timestamp) and Cache-Control headers (private; max-age=…) in the response accordingly.

When cache_seconds is not supplied or is 0, caching is disabled by setting the Cache-Control and Pragma headers to no-cache and removing the Expires header, if present.