REST api v2

Search…
REST api v2
REST api (v2)
We are expanding and improving the REST api. At its heart is a simplified query syntax called RSQL for collection queries For query syntax see RSQL parser. In addition we simplify the reading of entities.
Get
Key
Type
Description
attrs
Comma-separated string
Defines which fields in the API response to select
_method
HTTP method
Tunnel request through defined method over default API operation
Request
1
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>
2
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?attrs=attr0
3
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?attrs=attr0,attr1
4
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?attrs=attr0(subattr0,subattr1),attr1(*)
Copied!
1
POST http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?_method=GET
Copied!
1
POST http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?_method=GET
2
attrs=attr0(subattr0,subattr1),attr1(*)
Copied!
Delete
Request
1
DELETE http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>
Copied!
Query
We use the RSQL HTTP/URL based query language:
Key
Type
Description
q
Query string in RSQL
RSQL query to filter the entity collection response
sort
Query string in RSQL
Defines how entity collection response is sorted
attrs
Comma-separated string
Defines which fields in the API response to select
start
int
Offset in resource collection
num
int
Number of resources to retrieve starting at start
_method
HTTP method
Tunnel request through defined method over default API operation
1
GET http://molgenis.mydomain.example/api/v2/<entity_name>
2
GET http://molgenis.mydomain.example/api/v2/<entity_name>?attrs=attr0
3
GET http://molgenis.mydomain.example/api/v2/<entity_name>?attrs=attr0,attr1
4
GET http://molgenis.mydomain.example/api/v2/<entity_name>?attrs=attr0(subattr0,subattr1),attr1(*)
5
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0
6
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0:asc
7
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0:desc
8
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0:desc,attr1
9
GET http://molgenis.mydomain.example/api/v2/<entity_name>?start=40&num=20
10
GET http://molgenis.mydomain.example/api/v2/<entity_name>?q=attr0==val
11
GET http://molgenis.mydomain.example/api/v2/<entity_name>?q=attr0!=val
12
GET http://molgenis.mydomain.example/api/v2/<entity_name>?q=attr0!=val;attr1=ge=5
Copied!
See the MOLGENIS RSQL documentation for all supported operators in MOLGENIS and matching examples.
Aggregate contents
We also support aggregation of the result query:
Key
Type
Description
q
Query string in RSQL
RSQL query to filter the entity collection response
aggs
Aggregation query string in RSQL
Aggregation query to aggregate entities
The aggregation query supports the RSQL selectors 'x', 'y' and 'distinct' and the RSQL operator '=='. The selector 'x' defines the first aggregation attribute name, 'y' defines the second aggregation attribute name, 'distinct' defines the distinct aggregation attribute name.
1
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0
2
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0;y==attr1
3
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0;y==attr1;distinct=attr2
4
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0;y==attr1;distinct=attr2&q=attr4==val
Copied!
Join data from other tables
For simple lookup lists, it might be a convenience to include the list in the initial API response. You can do this for CATEGORICAL, and CATEGORICAL_MREF attributes using includeCategories.
Not including the query option will set it to the default false.
Key
Type
Description
includeCategories
boolean
Includes a list of categorical options in attribute metadata for CATEGORICAL and CATEGORICAL_MREF attributes
Sorting categorical options
You can add a unique, visible attribute to the metadata of the table after the ID-attribute to sort the categorical options.
NOTE: Make sure the ID-attribute is invisible.
Attribute definition
id
visible
unique
type
mySortAttribute
TRUE
TRUE
int
Metadata of target table
id
mySortAttribute
label
A
0
A very awesome category
B
2
A very busy category
C
1
A very complex category
When you call a V2 call with the includeCategories option this column will be used to sort on.
Example request - response
TableA
id
category
1
A
TableB
id
label
A
A very awesome category
B
A very busy category
C
A very complex category
Request
1
GET http://molgenis.mydomain.example/api/v2/TableA?includeCategories=true
Copied!
Response
1
{
2
  "meta": {
3
    "attributes": [
4
      {
5
        "name": "id"
6
      },
7
      {
8
        "name": "category",
9
        "categoricalOptions": [
10
          {
11
            "id": "A",
12
            "label": "A very awesome category"
13
          },
14
          {
15
            "id": "B",
16
            "label": "A very busy category"
17
          },
18
          {
19
            "id": "C",
20
            "label": "A very complex category"
21
          }
22
        ]
23
      }
24
    ]
25
  }
26
}
Copied!
Create/Add, Update, Delete by ID
Request
1
DELETE http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>
Copied!
Batch add/create
To create/add a list of entities into a collection you can POST the 'entities' parameter to a collection:
Request
1
POST http://molgenis.mydomain.example/api/v2/person
2
Content-Type: application/json
3
​
4
{entities: [
5
{
6
    "age": "101",
7
    "driverslicence": true
8
},
9
{
10
    "age": "102",
11
    "driverslicence": true
12
}
13
]}
Copied!
Response
1
201 Created
Copied!
Body
1
{
2
    location: "/api/v2/Person?q=id=in=("1","2")"
3
    resources: [{
4
        href: "/api/v2/Person/1"
5
    },
6
    {
7
        href: "/api/v2/Person/2"
8
    }]
9
}
10
​
11
* href: "/api/v2/Person/2" returns a created resource
12
* location: /api/v2/person/?q=id=in=(1,2) returns all created resources
Copied!
Batch update
To batch update a list of entities of a collection you can PUT the 'entities' parameter to a collection:
Request
1
PUT http://molgenis.mydomain.example/api/v2/person
2
Content-Type: application/json
3
​
4
{entities: [
5
{
6
    "id": 1,
7
    "age": "11",
8
    "driverslicence": true
9
},
10
{
11
    "id": 2,
12
    "age": "12",
13
    "driverslicence": true
14
}
15
]}
Copied!
Response
1
204 No Content
Copied!
Batch delete
(since v3.0.0)
To delete a list of entities of a collection you can DELETE the 'entityIds' parameter to a collection:
Request
1
DELETE http://molgenis.mydomain.example/api/v2/person
2
Content-Type: application/json
3
​
4
{
5
    entityIds: ["person0", "person1"]
6
}
Copied!
Response
1
204 No Content
Copied!
Body
1
{
2
    location: "/api/v2/Person?q=id=in=("1","2")"
3
    resources: [{
4
        href: "/api/v2/Person/1"
5
    },
6
    {
7
        href: "/api/v2/Person/2"
8
    }]
9
}
Copied!
One value
If you only want to change one attribute without needing to provide all other attributes:
Request
1
PUT http://molgenis.mydomain.example/api/v2/person/age
2
Content-Type: application/json
3
​
4
{entities: [
5
{
6
    "id": 1,
7
    "age": "1"
8
},
9
{
10
    "id": 2,
11
    "age": "2"
12
}
13
]}
Copied!
Response
1
204 No Content
Copied!
REST api v1
Files api
Last modified 8mo ago
Copy link
Contents
Join data from other tables
Create/Add, Update, Delete by ID