Rest-API

RPdb provides a Rest-API that can be used from other tools or frameworks like cURL. The usage and available endpoints are described in this section.

Versioning

The API is accessible via the URL https://rpdb.rpjosh.de/api/v1/. The program version of RPdb follows the semantic versionioning. Based on a version number in the format MAJOR.MINOR.PATCH, we increment the:

MAJOR version when API-incompatible changes are published. That means you may have to adjust some parts when you are using our API
MINOR version when we add new functionalities, that are compatible with the previous API. All endpoints are still working as with version MAJOR.0.0. In many cases there are deprecations that will be removed with the next major version
PATCH version when we make backward compatible bug fixes

Basically, we try to provide a transition period of at least four months between a deprecation in a MINOR version and the removal in the MAJOR version. That's also inportant for our offical clients so that they are still working for the time untill the user upgrades all clients.
In addition to the program version, we also use an API version. If very large changes are pending or the described transition time is not realizible, we raise the API version. For a limited time frame we provide two different API versions at the same time, to provide the describe transition time even in such complicated cases.

The following table lists all minor program versions with remarkable API changes, and the correspondending API version.

Program Version	API version	Introduced at	Remarkable Changes
3.0	`v1`	22.08.2022	Initial API version
3.1	`v1`	14.01.2023	Added attribute types `no_db` and `exec_response`. Changed version Endpoints
4.0	`v1`	14.04.2023	Extended `api-key` endpoint dramastically, added parameter presets to attribute
4.2	`v1`	14.11.2023	Added multiple parameters for an entry and parameter preset

Response

For almost all endpoints, our API produceses a JSON response body. When an erroneous request was sent (not a 2xx and 5xx response code), the response contains additional information for troubleshooting.

{
    "error": {
        "message": "The message description in the clients language",
        "id": "UNIQUE_ID_DESCRIBING_ERROR",
        "detailedErrorDescription": "An optional, technical description of the error",

        // These informations are only send when the debug mode of the applications is eabled in the server config
        "line": 136,
        "file": "src/Exception/AppException.php",
        "backtrace": [
            "#0: src/Exception/AppException.php (36)",
            "#1: src/Exception/AppException.php (136)",
            "#2: src/Helper/ValidationFactory.php (113)"
        ]
    }
}

Authentication and headers

For each request, the client can provide a set of generic headers. These are used to control the behaviour of the request.

Name	Type	Description
`Client-Date`	dateTime	The local time of the client → updates the time offset for the token / specifies the offset when no token was provided
`Client-Version`	string	The API-Version for which the client was designed for: `4.0.3`
`Java-Client`	mixed	The client will be treated like our Java Clients to set some default settings
`Language`	string	A two-digit Code (ISO 639) of the response language. Supported languages are `en` (English) and `de` (German)
`Multi-Instance`	bool	When an insert, update or delete of an entry or attribute was performed, the same token which made the change won't be notified for an update. When setting this flag, the same token will also be notified

For every call of the API (except the version and some user endpoints), the user has to be authorized. For that, you can specify the following headers in every request.

Name	Type	Description
`X-Api-Key`	string	Unique access token
`Username`	string	The user to authorize
`Password`	string	Password for the given `Username`

Besides the specification of the X-Api-Key in the Header, you can also use a cookie named rpdb_apiKey to store the token. You can create on with the api-key endpoint.
In sceneraious where you cannot set the headers, you can provide the API-Key also with a query parameter.

Warning

The specification of the API-Key with a query parameter is not recommended out of security reasons. The URL may be stored on the client in plaintext