REST Interface

Basic URL

The rest interface in Limbas can be accessed via the following URL. <limbasurl>/dependent/main_rest.php/

If needed, a “nicer” URL, such as <limbasurl>/api/, depending on the server configuration, a redirect can be added to the .htaccess file. In the environment variables, the setting restpath has to be adjusted accordingly. Example:

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^api/?(.*)$ /main_rest.php [NC,QSA]

Authorization

The registration in Limbas works by BASIC Auth. It is therefore sufficient to attach the following header to the request:

Authorization: Basic xxxxxxxxxxxxxxxxxxxx

Content Type

Limbas accepts the two following content types as a request body in POST/PATCH/DELETE, which must be given as request headers.

• Content-Type: application/json
• Content-Type: x-www-form-urlencoded

As a return you always get a JSON object.

URL Structure

There are three supported URL-Structure-Types: METHOD = GET / POST / PATCH / DELETE

1. Query on entire table: METHOD /tablename
2. Query on single record: METHOD /tablename/record-id
3. Query on linked records of a record: METHOD /tablename/record-id/linkingfield

Query Data (GET)

GET requests can be sent to all three URL structure types

Pagination

Is done via the parameter $page:

• $page[count] determines how many records are returned per page.
• $page[number] defines which page should be returned.

If the parameter is left out, all records are returned.

GET /kontakte?$page[count]=20&$page[number]=3 

Limit Fields

Is done via the parameter $fields. If this is not set, all fields of the active table are returned. Possible syntax:

• $fields=field1,field2: Only the fields name and first name are returned (Table implicitly defined by URL)
• $fields[tablename]=field1,field2: Same meaning, table implicitly defined
• $fields[tablename]=*: All fields of the table

Sorting

This is done via the parameter sort. Syntax:

• $sort=feld1,-feld2: First sort by field1 (ascending), then field2 (descending)
• $sort=tablename.field1,-tablename.field2: Same meaning, table explicitly defined

Filtering

Every table field can be moved with one or more filters. The respective field names of a table serve as parameters for the sorting. The following syntaxes are possible:

• fieldname=searchvalue The field fieldname has to be the exact keyword
• fieldname[operator]=searchvalue The field fieldname is searched with the certain operator
• tablename[fieldname]=searchvalue Differs only by explicit specification of the table
• tablename[fieldname][operator]=searchvalue Differs only by explicit specification of the table

Operators

The following operators are available: For numerical values:

• eq = equal
• neq = unequal
• lt = less than
• gt = greater than
• lte = less than or equal
• gte = greater than or equal

For text values:

• eq = equal
• contains = text contains search value
• startswith = text starts with search value
• endswith = text ends with search value

Archiving

If a table has active archiving, by default, only the data entries that are not archived will be returned. This can be adjusted like this:

• $archived=false Only not archived data entries are returned (default)
• $archived=true Only archived data entries are returned
• $archived=all All data entries are returned (no matter the archiving)

Validity

Über den Filter „validity“ kann eine mit dem Parameter „validity“ gekennzeichnete Tabelle nach einem Datum gefiltert und somit nur die in diesem Zeitraum gültigen Datensätze angezeigt werden. NULL Werte in den entsprechenden von/bis Feldern werden als gültig betrachtet. Folgende Werte sind zulässig

If a table has the “validity” parameter, you can use the filter “validity” to filter for a specific date. The returned data entries will only be the ones that match the given time frame. Using NULL in the from/ to fields is valid. These values are possible:

• $validity=[DATE] (valid data entries matching the date are returned)
• $validity=all (valid and invalid data entries are returned)
• $validity=allfrom (valid and future data entries are returned)
• $validity=allto (valid and past data entries are returned)

Add Record (POST)

POST requests to create a record can only be sent to Type 1 URLs. The ID is always assigned by Limbas and can not be preassigned. Mandatory in the request body is the “data” element. Within the “data” element, the attributes to update are specified as key-value-pairs, where Key is the respective field name.

POST / kunden
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx
{
 "data": {
   "name":“Max Mustermann“
   "strasse":"Musterweg 1",
   "plz":"12345",
   "ort":"Musterort"
 }
}

Return

The answer is the newly created data record.

Update Record (PATCH)

A PATCH request can only be related to specific data records. Therefore, only URL structure types 2 and 3 are allowed. Mandatory in the request body is the “data” element. Within the data element, the attributes to update are specified as key-value pairs, where Key is the field name.

PATCH /kunden/1
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx
{ 
 "data": {
   "strasse":"Musterweg 1",
   "plz":"12345",
   "ort":"Musterort"
 }
}

Return

In response, you get the entire updated record.

Delete Record (DELETE)

A DELETE request to a Type 2 URL removes a specific record. It is not possible to delete all data records of a table at once.

DELETE /kunden/1
Authorization: Basic xxxxxxxxxxxxxxxxxxxx

Return

• 204 – No Content
• 400 – Deletion failed
• 404 – Not found

Links

Links are always specified as a relational object with a single attribute “id”.

{"id":“1“}.

Add Link (POST)

POST requests to type 3 URLs allow you to add links to a record. Existing links are not overwritten.

POST /kunden/1/kontakte
{
 "data": [
   { "id": "1" },
   { "id": "2" }
 ]
}

Update Links (PATCH)

PATCH requests can be used to update the links of a data record. This replaces existing links. The PATCH call is possible in two different ways:

• Type 3: directly to the link: PATCH /tablename/record-id/linkfield
• Type 2: As attribute by PATCH to the main record PATCH /tablename/record-id

Unique Link

For a unique link, the value of “data” corresponds to exactly one relational object. If the value is zero for a unique link instead of a relation object, the link is deleted.

PATCH /kunden/1/boss
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx
{ 
 "data": { "id": "1" }
} 

Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx 
{ 
 "data": {
   "boss": {
     "data": { "id": "1" }
   }
 }
} 

Many-Links

For a Many-Link, the data element is an array of link objects. If data is an empty array, all links are deleted.

PATCH /kunden/1/kontakte
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx 
{
 "data": [
   { "id": "1" },
   { "id": "2" }
 ]
}

PATCH /kunden/1
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx 
{ 
 "data": {
   "kontakte": {
     "data": [
       { "id": "1" },
       { "id": "2" }
     ] 
   }
 }
} 

Delete Link (DELETE)

Equivalent to adding links by POST, DELETE removes them. In no case will entire records be deleted.

Unique-Links

For Unique-Links, a DELETE request to the Type 3 URL is sufficient to remove the corresponding link.

DELETE /kunden/1/boss
Authorization: Basic xxxxxxxxxxxxxxxxxxxx

Many-Links

Many-Links require specific records to be de-linked. Deleting all links at once is not possible. Remove the links from the customer with the ID 1 to the contacts with the IDs 1 and 2

DELETE /kunden/99
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx
{ 
 "data": [
       { "id": "1" },
       { "id": "2" }
     ]
}