Labii API is a REST API and it supports all different calling methods.

URL

An object has two types of URL represent two different views:

• List of objects

  {{base_url}}/{app}/{model}/list/{level}/{sid}/{serializer}/

• Detail of an object

  {{base_url}}/{app}/{model}/detail/{sid}/

Wheres,

• base_url=https://www.labii.dev/. If your organization has a dedicated server, the base_url=https://[your subdomain].labii.dev/

• app, the name of the application. See here for more details.

• model, the name of the model. See here for more details.

• level, the scope of records to retrieve. See Levels for more details.

• sid, Static and encrypted Labii object id. It has to match with level. For level=organization, the sid have to be the sid of the organization.

• serializer, the scope of fields of the return data

  • name, return only sid and name, very fast

  • list, return selected fields of the objects, fast

  • detail, return all fields of the objects, slow

Objects

You can use Labii API to query these objects:

Levels

Levels define the scope of records to retrieve. It is a required parameter for list API. These levels are used at Labii:

• organization: return the results within the organization level

• user: return the results for a particular user (deprecated)

• project: return the results for a project (deprecated)

Not all levels are available for all list API. Error of HTTP_406_NOT_ACCEPTABLE will return if a wrong level is used. The table below lists all allowed levels:

Methods

Here is the list of methods used:

• GET: Fetch one or more objects

• POST: Create an object

• PUT: Update an object

• PATCH: Partially update an object

• DELETE: Remove an object

Different roles have different permissions in using the methods. There are five roles at the organization level:

• Admin: The administrators

• Member: The members of the organization

• Alumni: The members who have left the organization

• User: Other Labii users who do not belong to the organization

• Anonymous: Unauthorized user

And 3 roles at the project level:

• Project Admin: The administrator of a project

• Project Edit: The members have edit permission at the project

• Project View: The members have view permission at the project

Serializer

Serializer is used to convert the data from the database into a different format. Each serializer in Labii represents a different field set to be returned. Labii supports the following serializers:

• name: return the field of sid and name of a record.

• list: return some basic fields. The set of fields varies for different tables.

• detail: return a full set of fields.

Status Codes

Here is a list of status code used by Labii API:

• HTTP_200_OK: return when API call successful

• HTTP_201_CREATED: return when an object is created

• HTTP_204_NO_CONTENT: return when an object is successfully deleted

• HTTP_401_UNAUTHORIZED: return when the user is not authenticated

• HTTP_403_FORBIDDEN: return when a user does not have permission

• HTTP_406_NOT_ACCEPTABLE: return when parameter is not correct

• HTTP_500_INTERNAL_SERVER_ERROR: return on internal errors

Errors

These are common errors for the list view and detail view.

List view

• HTTP_401_UNAUTHORIZED - token is not valid

• HTTP_403_FORBIDDEN - the user does not have permission to perform the action

• HTTP_406_NOT_ACCEPTABLE - some parameter provided is not acceptable

  • Wrong level - the level provided is not valid or is not allowed

  • Wrong sid - the sid provided can be not decrypted, or does not match any records

  • Wrong field - Error: the field (xxx) is not allowed!

  • Wrong datatype - list, acceptable data is DICT. Please POST multiple times if you have more than one dataset.

Detail view

• HTTP_401_UNAUTHORIZED - token is not valid

• HTTP_403_FORBIDDEN - the user does not have permission to perform the action

• HTTP_406_NOT_ACCEPTABLE - some parameter provided is not acceptable

  • Wrong sid - the sid provided can be not decrypted, or does not match any records

  • Wrong field - Error: the field (xxx) can not be updated!

Example

Get a list of records with curl:

curl -X get https://www.labii.dev/tables/rows/list/organization/xxx/list/ -H "Authorization: Token xxxx"

In Python:

import requests
headers = {
    "X-Forwarded-For": "batch",
    "Content-Type": "application/json",
    "Authorization": "Token %s" % token
}
requests.get(url="https://www.labii.dev/tables/rows/list/organization/xxx/list", headers=headers)