Interfaces REST Interface Estimated reading: 7 minutes Notiz: For using the REST-API, PHP version 7.1.0 or newer is required. 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 Query on entire table: METHOD /tablename Query on single record: METHOD /tablename/record-id 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. Example GET /kontakte?$page[count]=20&$page[number]=3 divides the result into pages of 20 records each and returns page 3. In the server’s response, related pages (first, prev, next, last) are displayed below the top level entry left according to the HATEOAS-principle. 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. Example In the following, a new customer is created. 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. Example Subsequently, the address of the customer with the ID 1 is updated. 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. Example Deleting the customer with the ID 1 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”. Example Record with ID 1: {"id":“1“}. Add Link (POST) POST requests to type 3 URLs allow you to add links to a record. Existing links are not overwritten. Example Customer with ID 1 will be added contacts with IDs 1 and 2. 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. Example The customer can have exactly one boss. As a boss, the customer ID 1 is now to be assigned the contact record with the ID 1. Variant 1: PATCH to boss relation of the customer with the ID 1 PATCH /kunden/1/boss Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": { "id": "1" } } Variant 2: PATCH to the customer with the ID 1 and the link as an attribute PATCH /kunden/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. Example The contacts with the ID’s 1 and 2 are supposed to be added o the customer with the ID 1. Variant 1: PATCH to customer contact relation with ID 1 PATCH /kunden/1/kontakte Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": [ { "id": "1" }, { "id": "2" } ] } Variant 2: PATCH to the customer with the ID 1 and the link as an attribute 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" } ] }
