Concepts
The Labii API is a REST API that provides programmatic access to the Labii platform.
The Labii API is a REST API that provides programmatic access to the Labii platform. It supports all different calling methods, including GET, POST, PUT, and DELETE.
The Labii API is designed to be accessible and flexible, allowing developers to use the programming language and tools of their choice to interact with the Labii platform. The API is fully documented and provides detailed information about each of its endpoints, including the HTTP method, endpoint URL, required parameters, and expected response.
Some of the key features of the Labii API include:
- 1.Resource-based architecture: The Labii API uses a resource-based architecture, which means that each endpoint represents a specific resource in the Labii platform, such as a project, experiment, or row.
- 2.Authentication and authorization: The Labii API uses OAuth 2.0 for authentication and authorization, ensuring that only authorized users can access sensitive data.
- 3.Pagination and filtering: The API provides support for pagination and filtering, allowing developers to retrieve specific subsets of data based on various criteria.
The Labii API uses two types of URLs to represent two different views of an object:
- 1.List of objects:
{{base_url}}/{app}/{model}/list/{level}/{sid}/{serializer}/
- 2.Detail of an object:
{{base_url}}/{app}/{model}/detail/{sid}/
The
base_url
is set to https://www.labii.dev/
by default. If your organization has a dedicated server, you can use https://[your subdomain].labii.dev/
as the base_url
.The
app
parameter represents the name of the application, while the model
parameter represents the name of the model. You can refer to the Labii documentation for more details on these parameters.The
level
parameter represents the scope of records to retrieve. You can refer to the Levels section of the Labii documentation for more details on this parameter.The
sid
parameter is a static and encrypted Labii object ID. It must match with the level
parameter. For example, if level=organization
, the sid
parameter must be the SID of the organization.Finally, the
serializer
parameter represents the scope of fields of the return data. There are three options available:name
: Returns only the SID and name of the object, which is very fast.list
: Returns selected fields of the objects, which is fast.detail
: Returns all fields of the objects, which is slow.
The Labii API provides various objects that represent different types of entities in the Labii platform, each with a set of methods for interacting with that entity. Below is a list of objects available in the Labii API along with their descriptions, the app they belong to, and their corresponding model:
Name | Description | App | Model |
---|---|---|---|
Organization | Represents the organization object | organizations | organization |
Personnel | Represents a member of the organization | organizations | personnel |
Team | Represents a team of the organization | organizations | team |
Organization Widget | Represents the installed widgets in the organization | organizations | organizationwidget |
Statement | Represents the monthly statement | organizations | statement |
Backup | Represents the backup data | organizations | backup |
Project | Represents the project object | projects | project |
Project Member | Represents a project member or team | projects | member |
Table | Represents the table object | tables | table |
Column | Represents the columns of a table | tables | column |
Row | Represents the rows of a table | tables | row |
Cell | Represents the cells of a row | tables | cell |
Section | Represents the sections of a row | tables | section |
Version | Represents the versions of a row | tables | version |
Filter | Represents the filters of a table | tables | filter |
Workflow | Represents the workflow of a table | tables | workflow |
Step | Represents the steps of a workflow | tables | step |
Activity | Represents user activities | activities | activity |
Widget | Represents the widget object | widgets | widget |
Levels define the scope of records to retrieve. The level parameter is a required parameter for the list API. Labii uses the following levels:
- organization: returns the results within the organization level.
- user: returns the results for a particular user (deprecated).
- project: returns the results for a project (deprecated).
Not all levels are available for all list APIs. If a wrong level is used, an HTTP_406_NOT_ACCEPTABLE error will be returned. The table below lists all the allowed levels for each API.
List API | level=organization | level=user | level=project |
Organization List | Yes | Yes | - |
Organization Member List | Yes | - | - |
Team List | Yes | Yes | - |
Organization Widget | Yes | - | - |
Statement List | Yes | - | - |
Backup List | Yes | - | - |
Project List | Yes | Yes | - |
Project Member List | Yes | - | Yes |
Table List | Yes | - | - |
Column List | Yes | - | - |
Filter List | Yes | Yes | - |
Row List | Yes | Yes | Yes |
Cell List | Yes | - | - |
Section List | Yes | - | - |
Version List | Yes | - | - |
Activity | Yes | Yes | - |
Widget | * | - | - |
The following documentation describes the methods used in the Labii API:
- GET: This method is used to fetch one or more objects.
- POST: This method is used to create an object.
- PUT: This method is used to update an object.
- PATCH: This method is used to partially update an object.
- DELETE: This method is used to 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
API | GET | POST | PUT | PATCH | DELETE |
Organization List | Admin, Member | Admin | - | - | - |
Organization Detail | Admin, Member | - | - | Admin | - |
Organization Member List | Admin, Member | Admin | - | - | - |
Organization Member Detail | Admin, Member | - | - | Admin | - |
Team List | Admin, Member | Admin | - | - | - |
Team Detail | Admin, Member | - | - | Admin | Admin |
Organization Widget List | Admin, Member | Admin | - | - | Admin |
Organization Widget Detail | Admin, Member | - | - | - | Admin |
Statement List | Admin | - | - | - | - |
Statement Detail | Admin | - | - | - | - |
Backup List | Admin | Admin | - | - | - |
Backup Detail | Admin | - | - | - | - |
Project List | Admin, Project Admin, Project Edit, Project View | Admin | - | - | - |
Project Detail | Admin, Project Admin, Project Edit, Project View | - | - | Admin, Project Admin | - |
Project Member List | Admin, Project Admin, Project Edit, Project View | Admin, Project Admin | - | - | - |
Project Member Detail | Admin, Project Admin, Project Edit, Project View | - | - | Admin, Project Admin | Admin, Project Admin |
Table List | Admin, Member | Admin | - | - | - |
Table Detail | Admin, Member | - | - | Admin | - |
Column List | Admin, Member | Admin | - | - | - |
Column Detail | Admin, Member | - | - | Admin | - |
Filter List | Admin, Member | Admin, Member | - | - | - |
Filter Detail | Admin, Member | - | - | Admin, Member | Admin, Member |
Row List | Admin, Project Admin, Project Edit, Project View | Project Admin, Project Edit | - | Project Admin, Project Edit | - |
Row Detail | Admin, Project Admin, Project Edit, Project View | - | - | Project Admin, Project Edit | - |
Cell List | Admin, Project Admin, Project Edit, Project View | Project Admin, Project Edit | - | - | - |
Cell Detail | - | - | - | Project Admin, Project Edit | - |
Section List | Admin, Project Admin, Project Edit, Project View | Project Admin, Project Edit | - | - | - |
Section Detail | Admin, Project Admin, Project Edit, Project View | - | - | Project Admin, Project Edit | - |
Version List | Admin, Project Admin, Project Edit, Project View | - | - | - | - |
Version Detail | Admin, Project Admin, Project Edit, Project View | - | - | - | - |
Activity List | Admin, Member | - | - | - | - |
Activity Detail | - | - | - | - | - |
Widget List | Admin, Member | - | - | - | - |
Widget Detail | Admin, Member | - | - | - | - |
The Serializer in Labii API 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 API supports the following serializers:
- name: This serializer returns the field of sid and name of a record.
- list: This serializer returns some basic fields. The set of fields varies for different tables.
- detail: This serializer returns a full set of fields.
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
These are common errors for the list view and 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 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.
- 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!
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)
Last modified 4mo ago