API User Manual-1
API User Manual-1
1- INTRODUCTION
The LabCollector Web Service Application Programming Interface (API) allows
third-party applications to interact with LabCollector's database (modules) and add-
ons (ELN and LSM).
Note: Since June 2017 API v1 was discontinued and all new evolutions are in API v2.
v. 2.0 - Page 3 of 26
LABCOLLECTOR API
2- LABCOLLECTOR API
2-1. API setup
First of all, you have to declare your application in your LabCollector software.
To access the application declaration setup form, log-in to LabCollector with super-
administrator rights and go to Admin > Setup page. Then select the Web Service API
link.
You are now on the Web Service API applications management page. To declare a new
application, simply complete this form:
The Application list shows all the applications for your LabCollector and you can, at
any time, modify their scope.
You have also access to the Token which is necessary to identify your application
during requests to the API.
v. 2.0 - Page 4 of 26
LABCOLLECTOR API
Note: To use this feature, you need to activate Curl on your PHP preferences.
In Linux, install the PHP-Curl package.
On windows and with our automatic installer, edit PHP.ini and uncomment
extensions for Curl (extension=php_curl.dll).
2-2. Requests
The dialog between third-party applications and the LabCollector web service API is
based on the HTTP 1.1 protocol.
You can send HTTP or HTTPS requests to the web service with a method to act on a
resource.
• GET method for reading a resource
• POST method to create a new resource
• PUT method to modify a resource
• DELETE method to delete a resource
2-2-2. Headers
• The X-LC-APP-Auth header where you put your application token which is
necessary to authorize your request to the API.
v. 2.0 - Page 5 of 26
LABCOLLECTOR API
encoding and to correctly convert your POST and PUT requests to the
LabCollector's character encoding (ISO 8859-1).
2-2-3. Tool
You can try to retrieve data from or send data to the API with some software app as
Postman (https://www.getpostman.com/).
Each LabCollector module data is identified by a unique URI (see annex for a complete
list of module's URI):
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]
This request replies the list of all data in a module.
You can do searching into module data by adding parameters to your URI. You can
pass a parameter with a keyword matching a field value, like:
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?name=[KEYWORD]
e.g.
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?name=First%20Record
This request returns the records where their name value contains the “First Record” keyword.
They are some custom parameters that the API uses to perform searching and filtering
actions.
Custom parameters
v. 2.0 - Page 6 of 26
LABCOLLECTOR API
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?record_id=[RECORD_ID]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?record_id=1,19
This request returns records with ID 1 and ID 19. You can specify multiple IDs by separating them
with a comma.
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?by_keywords=[KEYWORD]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?by_keywords=cell
This request performs a search into all fields of all records and returns matching cell. You can
specify multiple keywords by separating them with a comma.
• The fields parameters, If you want to retrieve only some fields values in the
API response:
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?fields=[FIELD1],[FIELD2]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?fields=count,name
This request returns all records from the module but with only count and name fields. You can specify
multiple fields by separating them with a comma.
The request accepts now multiple values separated by a comma, for custom fields of
type "select"
v. 2.0 - Page 7 of 26
LABCOLLECTOR API
• The search_on parameter allows you to search for data. And you can use it
to search by date range as follow:
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]&
search_on=date_field&from=XXXXXX&to=ZZZZZZ
If you only use FROM, the result will give all dates bigger than the FROM date. If you only use
TO, it will return all the value until this date.
v. 2.0 - Page 8 of 26
LABCOLLECTOR API
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?sort_by=[FIELD1]_DESC
e.g. [PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?sort_by=name_DESC
This request returns all records sorted in descending order on the name field. You can specify
multiple sort_by separating them with a comma and specified order ascendant “_ASC” or
descendant “_DESC” for each field.
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]?limit_to=0,10
This request returns 10 records beginning at index 0. If you do not specify the index, only the
number of results indicated is returned.
The API also returns two custom fields in the header response, “X-LC-QUERY-RESULT”
containing the number of results returned in the body response and “X-LC-QUERY-
TOTAL” containing the total of records matching your search.
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]/[DATA_ID]
This request replies a unique record. [DATA_ID] must match the unique ID of the record you want
to retrieve.
Storage
You also have Tube Sorter filtering functions for every items linked to storage:
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&box_i
d=[BOX_ID]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&box_i
d=34
This request returns storage info on box ID 34 like tube sorter. You can specify multiple IDs by separating
them with a comma.
v. 2.0 - Page 9 of 26
LABCOLLECTOR API
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&box_i
d=[BOX_ID]&record_name=[RECORD_NAME]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&box_i
d=206&record_name=ST-260
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&recor
d_name=[RECORD_NAME]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&recor
d_name=ST-260
These requests perform filtering on record named ST-260. You can specify multiple record names by
separating them with a comma. You can also specify box ID, here 206.
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&box_n
ame=[BOX_NAME]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=tube_sorter&box_n
ame=test-rack_06
This request performs filtering on box test-rack_06. You can specify multiple box names by separating
them with a comma.
v. 2.0 - Page 10 of 26
LABCOLLECTOR API
• facility_name
It will return empty boxes as well.
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]&data_id=[DATA_ID]&
fields=storage_sec
Product lot
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getLot
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getLot&lo
t_id=1/LT
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getLot&ch
em_id=2
v. 2.0 - Page 11 of 26
LABCOLLECTOR API
Optional parameters are lot_id (in format 1 or 1/LT) and chem_id. If it doesn't receive
parameters, then it retrieves all active lots.
Recipe
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getRecipe
s
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getRecipe
&recipe_id=[record_id]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getRecipe
&recipe_id=509
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getRecipe
Logs
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getRecipe
Report&log_id=[record_id]
e.g. [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action=getRecipe
Report&log_id=1218
v. 2.0 - Page 12 of 26
LABCOLLECTOR API
getRecipes prints the following info for that recipe_id: id, name, description, category
and then the components
v. 2.0 - Page 13 of 26
LABCOLLECTOR API
getRecipeReport prints the report PDF for that log_id under the format base64 that
can be decoded into PDF.
To create a new resource, simply send a request with the POST method to the desired
module URI:
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]
Check for uniqueness fields have been added, when creating new records (POST) or
update (PUT)
If exists a different record with the same value for a field Uniqueness, API will not
complete the action and will return code 409 (Conflict), and the text: Value for field
'XXX' must be unique. Value 'YYY' already exists in table 'ZZZ'. (see screenshot)
v. 2.0 - Page 14 of 26
LABCOLLECTOR API
Note: project_code field can be use in POST and PUT and it expects text (not id). You
can now create a new project code if it does not exists and if the operator has
permissions enough (administrator or super-administrator).
[PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2&action= addBox
- Required parameters:
o name
o type (must be a valid type: box, box_nogrid, plate, microplate, visotube,
bag, shelfpart)
o equipment (supports id or name and must exist in LabCollector storage).
o size (depends on the type of box: should be numeric for a visotube, and
the format (A:1.H:8) for a box, a plate, and a microplate)
- Optional parameters:
o description
o rack
o keeper
v. 2.0 - Page 15 of 26
LABCOLLECTOR API
To modify a resource, simply send a request with the PUT method to the desired
record URI:
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]/[DATA_ID]
Your parameter keys have to match the field’s name you want to modify.
For the following actions, note that for PUT request, parameters must be on the body
(not in URL).
The URL is [PATH_TO_LABCOLLECTOR]/webservice/index.php?v=2
The headers are: X-LC-APP-Auth, Accept.
• Remove Volume
- Parameters:
o removeVolume (mandatory)
o barcode, unique_code or aliquot_barcode (one of them must be
present)
o quantity (mandatory)
- Response: OK
• Remove Storage
- Parameters:
o removeStorage (mandatory)
o barcode, unique_code or aliquot_barcode (one of them must be
present)
- Response: OK
v. 2.0 - Page 16 of 26
LABCOLLECTOR API
Note: An error message is returned if mandatory parameters are not present; if the
barcode does not exist; if the unique_code is present, but it isn't unique; and, if the
color is present but it doesn't exist.
If the parameter box_details is not received and the type of box needs position (box
with grid, tube tray, or microplate), an error message is returned.
v. 2.0 - Page 17 of 26
LABCOLLECTOR API
Note: project_code field can be use in POST and PUT and it expects text (not id). You
can now create a new project code if it does not exists and if the operator has
permissions enough (administrator or super-administrator).
To delete a resource, simply send a request with the DELETE method to the desired
record URI:
[PATH_TO_LABCOLLECTOR]/webservice/v2/[MODULE]/[DATA_ID]
v. 2.0 - Page 18 of 26
API ERROR MESSAGES
Response
Message Description
code
'Requires application 401 The request either does not
authentication to access the Unauthorized have the header parameter X-
Web Service' LC-APP-Auth or does not have
a valid value
'Invalid Action xxx’ 400 Parameter action has a
Bad Request different value to ‘tube_sorter’
or ‘getBackup’
Missing Search Parameters! 400 The request contains the
Bad Request parameter Action=tube_sorter
but it is missing at least one of
the following parameters:
box_id, box_name,
record_name, unique_code,
barcode, aliquot_barcode
'Module “XXX" does not 400 The value of the parameter
exist!' Bad Request ‘module’ is not a LabCollector
module
'Module "XXX" does not share 403 The value of the parameter
this data!' Forbidden ‘module’ is not checked on
LabCollector > Admin > Setup
> Web service
‘The format of the request is 415 The parameter Accept is used,
not accepted!' Unsupported but the value is not one of the
Media Type accepted values:
application/XML or
application/JSON
(Empty) 406 The method must be one of
Not the following: GET, POST, PUT,
Acceptable DELETE
'No data found.' 404 No data found with this
Not Found request’s parameters
'OK.' 200 Record updated successfully
OK
v. 2.0 - Page 19 of 26
API ERROR MESSAGES
v. 2.0 - Page 20 of 26
LABCOLLECTOR WEB SERVICE API - ANNEX
webservice/v2/strains/[DATA_ID]
GET
webservice/index.php?v=2&module=strai Strains & Cells Unique record
ns&data_id=[DATA_ID] PUT
webservice/v2/strains/customfields
List of custom
webservice/index.php?v=2&module=strai GET Strains & Cells
ns&getModuleCustomFields=1 fields
webservice/v2/strains/organisms
List of
webservice/index.php?v=2&module=strai GET Strains & Cells
ns&getModuleOrganisms=1 organisms
webservice/v2/plasmids
GET List of all
webservice/index.php?v=2&module=plas Plasmids
mids POST records
webservice/v2/plasmids/[DATA_ID]
GET
webservice/index.php?v=2&module=plas Plasmids Unique record
mids&data_id=[DATA_ID] PUT
webservice/v2/plasmids/customfields
List of custom
webservice/index.php?v=2&module=plas GET Plasmids
mids&getModuleCustomFields=1 fields
webservice/v2/primers
GET List of all
webservice/index.php?v=2&module=pri Primers
mers POST records
webservice/v2/primers/[DATA_ID]
GET
webservice/index.php?v=2&module=pri Primers Unique record
mers&data_id=[DATA_ID] PUT
List of custom
webservice/v2/primers/customfields GET Primers
fields
v. 2.0 - Page 21 of 26
LABCOLLECTOR WEB SERVICE API - ANNEX
webservice/index.php?v=2&module=pri
mers&getModuleCustomFields=1
webservice/v2/chemicals
GET Reagents & List of all
webservice/index.php?v=2&module=che
micals POST Supplies records
webservice/v2/chemicals/[DATA_ID]
GET Reagents &
webservice/index.php?v=2&module=che Unique record
micals&data_id=[DATA_ID] PUT Supplies
webservice/v2/chemicals/customfields
Reagents & List of custom
webservice/index.php?v=2&module=che GET
micals&getModuleCustomFields=1 Supplies fields
webservice/v2/samples
GET List of all
webservice/index.php?v=2&module=sam Samples
ples POST records
webservice/v2/samples/[DATA_ID]
GET
webservice/index.php?v=2&module=sam Samples Unique record
ples&data_id=[DATA_ID] PUT
webservice/v2/samples/customfields
List of custom
webservice/index.php?v=2&module=sam GET Samples
ples&getModuleCustomFields=1 fields
webservice/v2/samples/organisms
List of
webservice/index.php?v=2&module=sam GET Samples
ples&getModuleOrganisms=1 organisms
webservice/v2/samples/types
List of sample
webservice/index.php?v=2&module=sam GET Samples
ples&getModuleTypes=1 types
webservice/v2/antibodies
GET List of all
webservice/index.php?v=2&module=anti Antibodies
bodies POST records
webservice/v2/antibodies/[DATA_ID]
GET
webservice/index.php?v=2&module=anti Antibodies Unique record
bodies&data_id=[DATA_ID] PUT
webservice/v2/antibodies/customfields
List of custom
webservice/index.php?v=2&module=anti GET Antibodies
bodies&getModuleCustomFields=1 fields
webservice/v2/sequences
GET List of all
webservice/index.php?v=2&module=seq Sequences
uences POST records
v. 2.0 - Page 22 of 26
LABCOLLECTOR WEB SERVICE API - ANNEX
webservice/v2/sequences/[DATA_ID]
GET
webservice/index.php?v=2&module=seq Sequences Unique record
uences&data_id=[DATA_ID] PUT
webservice/v2/sequences/customfields
List of custom
webservice/index.php?v=2&module=seq GET Sequences
uences&getModuleCustomFields=1 fields
webservice/v2/animals
GET List of all
webservice/index.php?v=2&module=ani Animals
mals POST records
webservice/v2/animals/[DATA_ID]
GET
webservice/index.php?v=2&module=ani Animals Unique record
mals&data_id=[DATA_ID] PUT
webservice/v2/animals/customfields
List of custom
webservice/index.php?v=2&module=ani GET Animals
mals&getModuleCustomFields=1 fields
webservice/v2/equipments
GET List of all
webservice/index.php?v=2&module=equi Equipment
pments POST records
webservice/v2/equipments/[DATA_ID]
GET
webservice/index.php?v=2&module=equi Equipment Unique record
pments&data_id=[DATA_ID] PUT
webservice/v2/equipments/customfields
List of custom
webservice/index.php?v=2&module=equi GET Equipment
pments&getModuleCustomFields=1 fields
webservice/v2/structures
GET Chemical List of all
webservice/index.php?v=2&module=stru
ctures POST Structures records
webservice/v2/structures/[DATA_ID]
GET Chemical
webservice/index.php?v=2&module=stru Unique record
ctures&data_id=[DATA_ID] PUT Structures
webservice/v2/structures/customfields
Chemical List of custom
webservice/index.php?v=2&module=stru GET
ctures&getModuleCustomFields=1 Structures fields
v. 2.0 - Page 23 of 26
LABCOLLECTOR WEB SERVICE API - ANNEX
webservice/v2/docs/customfields
List of custom
webservice/index.php?v=2&module=docs GET Documents
&getModuleCustomFields=1 fields
webservice/v2/docs/categories
List of
webservice/index.php?v=2&module=docs GET Documents
&getModuleCategories=1 categories
webservice/v2/abook
GET List of all
webservice/index.php?v=2&module=abo Address Book
ok POST records
webservice/v2/abook/[DATA_ID]
GET
webservice/index.php?v=2&module=abo Address Book Unique record
ok&data_id=[DATA_ID] PUT
webservice/v2/abook/customfields
List of custom
webservice/index.php?v=2&module=abo GET Address Book
ok&getModuleCustomFields=1 fields
webservice/v2/abook/categories
List of
webservice/index.php?v=2&module=abo GET Address Book
ok&getModuleCategories=1 categories
webservice/v2/microarrays
GET List of all
webservice/index.php?v=2&module=micr Microarrays
oarrays POST records
webservice/v2/microarrays/[DATA_ID]
GET
webservice/index.php?v=2&module=micr Microarrays Unique record
oarrays&data_id=[DATA_ID] PUT
webservice/v2/microarrays/customfields
List of custom
webservice/index.php?v=2&module=micr GET Microarrays
oarrays&getModuleCustomFields=1 fields
webservice/v2/microarrays/organisms
List of
webservice/index.php?v=2&module=micr GET Microarrays
oarrays&getModuleOrganisms=1 organisms
webservice/v2/[CUSTOM_MODULE_NAM
E] GET Custom List of all
webservice/index.php?v=2&module=[CU POST Module records
STOM_MODULE_NAME]
webservice/v2/[CUSTOM_MODULE_NAM
E]/[DATA_ID]
GET Custom
webservice/index.php?v=2&module=[CU Unique record
STOM_MODULE_NAME]&data_id=[DATA PUT Module
_ID]
v. 2.0 - Page 24 of 26
LABCOLLECTOR WEB SERVICE API - ANNEX
webservice/v2/[CUSTOM_MODULE_NAM
E]/customfields
Custom List of custom
webservice/index.php?v=2&module=[CU GET
STOM_MODULE_NAME]&getModuleCust Module fields
omFields=1
v. 2.0 - Page 25 of 26
http://www.labcollector.com
[email protected]