REST API

This short article explains basic information about our REST API.

Note: The current version of our webmate Java SDK can always be found on Maven-Central. You can have a look at the source code and find more information on GitHub. Examples on how to use the SDK are also available on GitHub. Additional SDKs and examples for other programming languages can be found in our webmate GitHub organization.

The webmate REST API is an interface which allows the user to interact with webmate without using the web UI.

A full specification of the API can be found in our Swagger API Documentation.

An HTTP Request containing the HTTP-Header as well as an endpoint is needed to communicate with the system. This is an example using the tool curl:

1
2
3

curl -H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "webmate.api-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=" \

If you are using an old API key of the format “c1e3effb-xxx-xxx-xxx-xxx” you also have to include the following header:

`1`	`-H "webmate.user: xxx@xxx.com" \`

HTTP Header

Input and Output Format

Data in webmate API requests is typically formatted as JSON (HTTP headers should be set accordingly). Here an example using curl:

`1`	`curl -H "Content-Type: application/json" -H "Accept: application/json"`

The input format (from client to server) is specified by setting the HTTP header Content-Type, while the format expected by the client is specified by Accept.

Authentication

Authentication for using the API is done using a user’s API key. If you are using on old API key of the format “c1e3effb-xxx-xxx-xxx-xxx”, the user’s email address is also needed.

E-mail: xxx@xxx.com
API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

In our example with curl, it would look like this:

`1`	`curl -H "webmate.api-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx="`

Access Type

webmate API mostly uses the following HTTP-Request-Types:

Command	Request
GET	Requests the data of a specific resource from the system, e.g. data of a job
POST	Sends data for further processing to the server, e.g. creating a new test with a specified input
PUT	Sets information of a resource that is already available in the system, e.g. the roles of a user
DELETE	Deletes an already available resource on the server, e.g. deleting a user

API Endpoint URIs

An endpoint is a URL pattern that uniquely identifies a resource in webmate.

The first part of the endpoint URL specifies the server that is being contacted by an API call. The REST API of the public webmate instance can be found here (Note: if you are accessing your own webmate instance, that URL will be different):

`1`	`https://api.webmate.io`

At some point, there may be different versions of webmate API endpoints (currently, all endpoints are using version v1). To distinguish different versions, the version number is part of the endpoint URL, e.g.,

`1`	`https://api.webmate.io/v1`

The complete list of endpoints available in webmate can be found in our Swagger API Documentation.

Example: If you want to request information about a device with ID “c558c3ab-ac37-468e-84xk-abz5d84cde69”, the complete endpoint address according to our API documentation would be:

`1`	`https://api.webmate.io/v1/device/devices/c558c3ab-ac37-468e-84xk-abz5d84cde69`