Get

updated: 2024-04-11 (v. 3.4.18)

Using the GET method, you can get lists of any listable classes, filter and order them, or look up an object with a specific ID.

Example:
GET /api/<class>/?<parameters>, e.g. GET /api/user/?detail

Listable classes

affectedgene - genotype affected genes
attachment - list of attachments
attachmenttype - shortened list of attachments - ID + attachment type
background - fishline background
config - facility configurations
counttype - count types
diet - diets
driver - gene drivers for genotypes
event - events for notifications
experiment - experiments
fishline - fishlines
genotype - genotypes
globaltarget - notification targets
group - permission groups
input - action log
input_condition - action log, type: Conditions
input_count - action log, type: Count
input_crossing - action log, type: Crossing
input_genotyping - action log, type: Genotyping
input_productivity - action log, type: Productivity
input_split - action log, type: Split
input_transfer - action log, type: Transfer
light - light conditions
message - your received messages
method - count type methods
modcategory - genotype modification categories
origin - fishline origins
permission - list of permissions - not permission groups
position - list of positions
positionblocktype - types of blocked positions
printer - printers
printertype - printer types
printingtemplate - printing templates
printlog - printing log
project- projects
rack - racks
request - requests
room - rooms
sex - sexes
source - fishline sources
species - species
stock- stocks
substock - substocks
substockuse - substock uses
triggeredgene - triggered genes used in genotypes
user - users
waterlog - water system logs
watersystem - water systems
workgroup - workgroups
zygosity - zygosities

GET parameters

All get parameters are optional.

Detail

Usually, when accessing one of the classes above, the result contains only basic information. If you need more detailed data (e.g. some M:N related objects expanded), you have to use parameter detail. But use it carefully - the response size and processing time may significantly increase.

Example:
GET /api/substock/?detail

Deleted objects

Deleted objects are excluded from all list requests by default. Parameter _all[=true] includes deleted objects in the list.

Example:
GET /api/substock/?_all

Paging

If the returned list exceeds a length limit, it is split into multiple pages and without any additional parameters, only the first page of the list is returned. You can change the page size and go through individual pages using the parameters below. The default value for page size is in the instance configuration under defaults.list.page_size.

pg_size - number of objects returned in one response, pg_size=0 returns all objects - this can lead to request timeout, in general, it is not ideal to use it without filters
pg - number of the requested page, counted from 1

Examples:
GET /api/substock/?pg_size=10&pg=3
GET /api/trigerredgene/?pg_size=0

Order

Lists can be ordered according to one or more attributes. The order can be set with a parameter o=<comma-separated list of attributes>. To sort data in descending order use - before the attribute.

Django lookups (double-underscore-separated path through the DB model) can be also used to sort, e.g. substocks can be sorted by stock__fishline__background__name.

Examples:
GET /api/substock/?o=-count,-stock__date_of_birth
GET /api/trigerredgene/?o=name

Filters

Every other parameter is considered to be a filter. If it is not a valid Django lookup (Django docs) the request will fail.

Look-up consists of a double-underscore-separated path through the DB model and an optional double-underscore-separated operator, e.g.:

/api/substock/?stock__date_of_birth__gte=2015-12-01 (gte is operator greater or equal),
/api/background/?name=ABC (missing operator means exact match).

Please note that the filter conditions are applied in conjunction (filter_1 AND filter_2 AND filter_3) and there is no way to put OR between them. Yet some special use cases of OR are available: operator in and combined lookup (see further sections).

Operators

Here is a list of some commonly used operators (those with leading i are case insensitive):

exact, iexact - exact match = equal
contains, icontains - contains given substring
containsall, icontainsall - contains all given substrings (comma-separated list)
like, ilike - SQL like, allows using some wildcards
startswith, istartswith, endswith, iendswith - starts or ends with given substring
gt, gte - greater than, greater than, or equal
lt, lte - less than, less than or equal
in - belongs to the given list of possible values
isnull - the attribute is not set

Negative filters

Lookups ending with ! are negative, e.g. in! means "not in", exact! means "≠".

Combined lookup

If you are looking for a sub-string (or whatever else) and you are not sure in what attribute should it be, you can search a few attributes at once with this feature. Just put comma-separated look-ups into square brackets:

[name_gen__icontains,description__icontains]=<something>

You can also mix operators:

[count__gte,description__icontains]=<something>

Or put the common operator out of the brackets (this is equivalent to the first example):

[name_gen,description]__icontains=<something>

Examples:

Square brackets have a special function in curl so you need to backslash them to work properly ("\[", "\]"). Similar issues may occur with other symbols such as "&".

GET /api/substock/?count__gt=10&id__in=12,13,15,16 - count > 10 and ID belongs to the list GET /api/substock/?id__in!=12,13,15,16&status__in!=dead,merged,split out&count=10
GET /api/substock/?[id__exact,stock_id__exact,stock__local_stock_id__exact,name_gen__icontains,position__fullname__icontains]=145 - this is a substock quick search filter GET /api/fishline/?genotypes__isnull - wild type fishlines GET /api/substock/?stock__fishline__genotypes__isnull - wild type substocks
GET /api/substock/?name_gen__icontainsall=abc,B52,E55 - substocks name_gen has to contain all of the given substrings

Response

The response contains 3 sections:

data
meta - metadata
- filters - filters used to get this list, split into 2 sections:
  - positive - e.g. count=10
  - negative - e.g. id__in!=1,3,5
- order
- filtered_count - number of objects matching used filter
- total_count - total number of objects in DB (not including deleted unless _all is used)
- page
- page_size
- max_page - maximal valid value for page
warnings - list of warning messages

Example 1

GET /api/sex/

{
  "data": [
    {
      "id": 1,
      "name": "unknown",
      "tag": null,
      "active": true
    },
    {
      "id": 2,
      "name": "male",
      "tag": "<i class=\"fa-fw fas fa-mars text-primary\" title=\"M\"></i>",
      "active": true
    },
    {
      "id": 3,
      "name": "female",
      "tag": "<i class=\"fa-fw fas fa-venus text-danger\" title=\"F\"></i>",
      "active": true
    }
  ],
  "meta": {
    "filters": {
      "positive": {},
      "negative": {}
    },
    "order": null,
    "filtered_count": 3,
    "total_count": 3,
    "page": 1,
    "page_size": 50,
    "max_page": 1
  },
  "warnings": []
}

Example 2 - Substock simple

GET /api/substock/?pg_size=1

{
  "data": [
    {
      "id": 16950,
      "count": 45,
      "substock_num": 12,
      "name_gen": "ubi:GFP<sup>+</sup> 2023-12-13/1  (12)",
      "facility_name_gen": "ubi:GFP<sup>+</sup>",
      "list_name_gen": "ubi:GFP<sup>+</sup>",
      "suffix": "",
      "date_of_death": null,
      "status": "unproductive",
      "sex_id": 1,
      "sex_name": "unknown",
      "productivity": "juvenile",
      "dominant_tag_id": null,
      "dominant_tag_name": null,
      "position_id": 541,
      "position_name": "E01",
      "light_id": 1,
      "light_name": "default",
      "diet_id": 1,
      "diet_name": "default",
      "stock_id": 7582,
      "parent_input_id": 97904,
      "crossing_parent_input_id": 97628,
      "substockuse_id": null,
      "substockuse_name": null,
      "description": "",
      "active": true,
      "project_id": null,
      "project_name": null,
      "project_name_gen": null,
      "current_author_id": 16,
      "updated": "2024-02-13T12:04:40.911767Z",
      "burdened": false,
      "to_print": false,
      "last_print": "2024-02-13",
      "experiment_id": null,
      "experiment_name": null,
      "experiment_name_gen": null,
      "most_severe_action_id": null,
      "actually_counted_to_experiment": false,
      "reused": false,
      "funding_id": null,
      "funding_name": null,
      "maturity": "adult",
      "age": 120,
      "age_weeks": 17,
      "local_stock_id": "7582",
      "status_cssclass": "unproductive",
      "icon": "adult",
      "position_fullname": "F09:E01",
      "position_width": 1,
      "facility_link": "/facility?rack_id=12&highlight=541",
      "date_of_birth": "2023-12-13",
      "generation": null,
      "printed": true,
      "tags": [],
      "dominant_tag": null,
      "dominant_tag_html": "",
      "tags_html": "",
      "max_severity_id": null,
      "species_id": null,
      "species_name": null,
      "full_description": "fishline: GMO APPROVED: 2012"
    }
  ],
  "meta": {
    "filters": {
      "positive": {},
      "negative": {}
    },
    "order": null,
    "filtered_count": 1,
    "total_count": 10492,
    "page": 1,
    "page_size": 1,
    "max_page": 1
  },
  "warnings": []
}

Example 3 - Substock detailed

GET /api/substock/?pg_size=1&detail

{
  "data": [
    {
    "id": 16950,
    "count": 45,
    "substock_num": 12,
    "name_gen": "ubi:GFP<sup>+</sup> 2023-12-13/1  (12)",
    "facility_name_gen": "ubi:GFP<sup>+</sup>",
    "list_name_gen": "ubi:GFP<sup>+</sup>",
    "suffix": "",
    "date_of_death": null,
    "status": "unproductive",
    "sex_id": 1,
    "sex_name": "unknown",
    "productivity": "juvenile",
    "dominant_tag_id": null,
    "dominant_tag_name": null,
    "position_id": 541,
    "position_name": "E01",
    "light_id": 1,
    "light_name": "default",
    "diet_id": 1,
    "diet_name": "default",
    "stock_id": 7582,
    "parent_input_id": 97904,
    "crossing_parent_input_id": 97628,
    "substockuse_id": null,
    "substockuse_name": null,
    "description": "",
    "active": true,
    "project_id": null,
    "project_name": null,
    "project_name_gen": null,
    "current_author_id": 16,
    "updated": "2024-02-13T12:04:40.911767Z",
    "burdened": false,
    "to_print": false,
    "last_print": "2024-02-13",
    "experiment_id": null,
    "experiment_name": null,
    "experiment_name_gen": null,
    "most_severe_action_id": null,
    "actually_counted_to_experiment": false,
    "reused": false,
    "funding_id": null,
    "funding_name": null,
    "maturity": "adult",
    "age": 120,
    "age_weeks": 17,
    "local_stock_id": "7582",
    "status_cssclass": "unproductive",
    "icon": "adult",
    "position_fullname": "F09:E01",
    "position_width": 1,
    "facility_link": "/facility?rack_id=12&highlight=541",
    "date_of_birth": "2023-12-13",
    "generation": null,
    "printed": true,
    "tags": [],
    "dominant_tag": null,
    "dominant_tag_html": "",
    "tags_html": "",
    "max_severity_id": null,
    "species_id": null,
    "species_name": null,
    "full_description": "fishline: GMO APPROVED: 2012",
    "genotypes_zygosities": [
      {
        "id": 22157,
        "genotype_id": 16,
        "genotype_name_gen": "-3.5ubi:GFP",
        "substock_id": 16950,
        "zygosity_id": 2,
        "zygosity_name": "+",
        "visible": true
      }
    ],
    "latest_crossings": [],
    "eggquantity_cssclass": "zb-status-eggquantity-none",
    "eggquality_cssclass": "zb-status-eggquality-none",
    "egg_quantity_avg": null,
    "egg_quality_avg": null,
    "background_id": 2,
    "background_name": "TU",
    "owners": [],
    "project": null,
    "projects": [],
    "experimental_project": null,
    "workgroups": [
      {
        "id": 6,
        "name": "Bartunek",
        "description": null,
        "active": true
      }
    ],
    "fishline_id": 20,
    "fishline_name": "ubi:GFP",
    "fishline_name_gen": "-3.5ubi:GFP",
    "fishline_attachments": [],
    "responsible": "facility",
    "responsible_id": 16,
    "rack_id": 12,
    "rack_name": "09",
    "room_id": 5,
    "room_name": "F",
    "stock_name": "ubi:GFP 2023-12-13/1",
    "species_settings": {},
    "diet_cssclass": "zb-status-default",
    "light_cssclass": "zb-status-default",
    "experiment_cssclass": "zb-status-default",
    "binary_experiment_cssclass": "zb-status-default",
    "printed_cssclass": "zb-status-default",
    "reused_cssclass": "zb-status-default",
    "reused_icon": "",
    "most_severe_action": null,
    "parents": [
      14076
    ],
    "inputs": [
      {
        "id": 63800,
        "type": "confirm_burden",
        "user_id": 20,
        "user": "nikol",
        "count_at_start": null,
        "position_at_start": null,
        "substock_id": null,
        "substock": null,
        "stock_id": null,
        "stock": null,
        "fishline_id": 20,
        "fishline": "ubi:GFP",
        "request_id": null,
        "request": null,
        "superior_id": null,
        "superior": null,
        "input_procedure_id": null,
        "input_procedure": null,
        "description": null,
        "created": "2022-02-15T09:29:59.612053Z",
        "performed": "2022-02-15",
        "performed_order": 50.0,
        "active": true,
        "projects": [],
        "item": null,
        "item_id": null,
        "item_type": "substock",
        "type_name": "Confirm Burden",
        "input_changes": [],
        "burdens": [],
        "substock_lsid": null,
        "subordinates": [],
        "age": null,
        "is_mine": false
      },
      {
        "id": 97627,
        "type": "update_s",
        "user_id": 16,
        "user": "facility",
        "count_at_start": null,
        "position_at_start": null,
        "substock_id": null,
        "substock": null,
        "stock_id": 7582,
        "stock": "ubi:GFP 2023-12-13/1",
        "fishline_id": null,
        "fishline": null,
        "request_id": null,
        "request": null,
        "superior_id": null,
        "superior": null,
        "input_procedure_id": null,
        "input_procedure": null,
        "description": "create",
        "created": "2023-12-13T12:22:28.719254Z",
        "performed": "2023-12-13",
        "performed_order": 50.0,
        "active": true,
        "projects": [],
        "item": "ubi:GFP 2023-12-13/1",
        "item_id": 7582,
        "item_type": "stock",
        "type_name": "Update Stock",
        "input_changes": [],
        "stockhistory_id": 3093,
        "stockhistory": "StockHistory object (3093)",
        "changes": {},
        "substock_lsid": null,
        "subordinates": [],
        "age": null,
        "changes_as_strings": [],
        "is_mine": false
      },
      {
        "id": 97943,
        "type": "genotype",
        "user_id": 16,
        "user": "facility",
        "count_at_start": 15,
        "position_at_start": "F14:F09",
        "substock_id": 16950,
        "substock": "ubi:GFP<sup>+</sup> 2023-12-13/1  (12)",
        "stock_id": null,
        "stock": null,
        "fishline_id": null,
        "fishline": null,
        "request_id": null,
        "request": null,
        "superior_id": 97904,
        "superior": "Action #97904 [SPLIT] on ubi:GFP<sup>+</sup> 2023-12-13/1  (1)",
        "input_procedure_id": null,
        "input_procedure": null,
        "description": "automatic assign at substock split",
        "created": "2023-12-19T10:13:43.094902Z",
        "performed": "2023-12-19",
        "performed_order": 70.0,
        "active": true,
        "projects": [],
        "item": "ubi:GFP<sup>+</sup> 2023-12-13/1  (12)",
        "item_id": 16950,
        "item_type": "substock",
        "type_name": "Genotyping",
        "input_changes": [],
        "substock_lsid": "7582",
        "subordinates": [],
        "age": 6,
        "zygosities": [
          {
            "genotype": "-3.5ubi:GFP<sup>+</sup>",
            "genotype_id": 16,
            "genotype_base": "-3.5ubi:GFP",
            "zygosity": "+",
            "zygosity_id": 2
          }
        ],
        "genotypingmethod_id": null,
        "genotypingmethod": null,
        "blamed_project_id": null,
        "blamed_project": null,
        "virtual": true,
        "genotypingmethod_severity_id": null,
        "genotypingmethod_severity": null,
        "genotypingmethod_severity_level": null,
        "substock_detail": {
          "owners": [],
          "responsible_user": "facility"
        },
        "is_mine": true
      }
    ]
  }  
  ],
  "meta": {
    "filters": {
      "positive": {},
      "negative": {}
    },
    "order": null,
    "filtered_count": 1,
    "total_count": 10492,
    "page": 1,
    "page_size": 1,
    "max_page": 1
  },
  "warnings": []
}