Overview
Overview of Labii API
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/ - sid, Static and encrypted Labii object id. It has to match with level. For
level=organization
, thesid
have to be thesid
of theorganization
. - serializer, the scope of fields of the return data
- name, return only
sid
andname
, very fast - list, return selected fields of the objects, fast
- detail, return all fields of the objects, slow
You can use Labii API to query these objects:
Name | Description | App | Model |
Organization | The organization object | organizations | organization |
Personnel | Member of the organization | organizations | personnel |
Team | Team of the organization | organizations | team |
Organization Widget | Installed Widgets | organizations | organizationwidget |
Statement | Monthly statement | organizations | statement |
Backup | Backup data | organizations | backup |
Project | The project object | projects | project |
Project Member | Project member or team | projects | member |
Table | The table object | tables | table |
Column | The columns of a table | tables | column |
Row | The rows of a table | tables | row |
Cell | The cells of a row | tables | cell |
Section | The sections of a row | tables | section |
Version | The versions of a row | tables | version |
Filter | The filters of a table | tables | filter |
Workflow | The workflow of a table | tables | workflow |
Step | The steps of a workflow | tables | step |
Activity | User activities | activities | activity |
Widget | The widget object | widgets | widget |
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: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 | * | - | - |
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
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 | - | - | - | - |
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.
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 1yr ago