Share:
TestBench CS Online Help 2.7

API specification

Advanced » Rest API » API specification

The TestBench server understands HTTP requests defined by the official standard. This compact overview of the methods we provide and the requests itself helps you get started with our API.

URI contents

Each call with .../tenant/ in the route affects the selected tenant only. Side effects between different tenants do not exist.

An example of a URI is:http://localhost:1234/api/tenants/:tenantId/products.
The HTTP request will create a product in the selected tenant whose tenantId is given in the URI.

That is also valid for a call with.../product/or.../user/or.../tenant/{tenantID}/productin the route.


HTTP Request

A standardized request header may look like this:
PATCH /api/1/udf/1337 HTTP/1.1
Host: localhost:9000
Authorization: Bearer dHQtYWRtaW46YWRtaW4=
Content-Type: application/vnd.testbench+json; charset=UTF-8

The first line defines the method you want to use and the URI, i. e. the path to the resource. The server only provides a few of the officially specified HTTP methods. In this form, the URI does not provide the host since it is already defined in the header. Note that special characters in the URI must be escaped by percent-escaping, e. g. "space" is escaped as "%20".

The content-type is application/vnd.testbench+json encoded in UTF-8. Ensure that you do not forget to specify the encoding in the content-type, just as the example above does. You can completely omit the content-type if you only want to make a GET request.

The request body, as well as the response body, are JSON objects. For every request, you will always get a response with a JSON body content.


HTTP Methods

The TestBench server understands a set of HTTP methods. Which method you use depends on the resource. A request with any of the methods will answer with an HTTP response containing an HTTP status code and a response body. You can read in our documentation which Response Codes the server uses and what the Response Bodies look like.

These are methods the server understands and their effects:
GET
A request to fetch one element or a set of elements from the resource.
POST
The POST method sends a request to add an element to the resource. For a successful POST, you need a body with the element you want to create. The element you want to send with your request has to be complete and syntactically correct. Otherwise, you will get an error response. POST will only create a new element if it does not already exist. The criteria of whether an element exists depends on the resource.
PATCH
This method is used to update an existing element in a resource. The request needs a body with the part of the element you want to update. You do not need to submit the whole element. Nevertheless, the syntax must be correct. If there is one incorrect attribute, the entire PATCH request will be canceled. PATCH only works on existing resources; you cannot update a resource that does not exist.
PUT
PUT is a method that updates the resource in every case, assuming the request was successful. If there is no such element in the resource, then PUT will just create a new one. If the element already exists, it will be updated. The identification of the element depends on the resource itself. For this behavior, it is essential to provide the full element in the PUT's request body. Even if you just want to update, you need to provide the whole element, just as you would create a new one.
DELETE
This method is used to remove a single element or a set of elements in the resource.