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

GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?attrs=attr0
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?attrs=attr0,attr1
GET http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?attrs=attr0(subattr0,subattr1),attr1(*)
POST http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?_method=GET
POST http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>?_method=GET
attrs=attr0(subattr0,subattr1),attr1(*)

Delete

Request

DELETE http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>

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

GET http://molgenis.mydomain.example/api/v2/<entity_name>
GET http://molgenis.mydomain.example/api/v2/<entity_name>?attrs=attr0
GET http://molgenis.mydomain.example/api/v2/<entity_name>?attrs=attr0,attr1
GET http://molgenis.mydomain.example/api/v2/<entity_name>?attrs=attr0(subattr0,subattr1),attr1(*)
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0:asc
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0:desc
GET http://molgenis.mydomain.example/api/v2/<entity_name>?sort=attr0:desc,attr1
GET http://molgenis.mydomain.example/api/v2/<entity_name>?start=40&num=20
GET http://molgenis.mydomain.example/api/v2/<entity_name>?q=attr0==val
GET http://molgenis.mydomain.example/api/v2/<entity_name>?q=attr0!=val
GET http://molgenis.mydomain.example/api/v2/<entity_name>?q=attr0!=val;attr1=ge=5

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.

GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0;y==attr1
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0;y==attr1;distinct=attr2
GET http://molgenis.mydomain.example/api/v2/<entity_name>?aggs=x==attr0;y==attr1;distinct=attr2&q=attr4==val

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

GET http://molgenis.mydomain.example/api/v2/TableA?includeCategories=true

Response

{
  "meta": {
    "attributes": [
      {
        "name": "id"
      },
      {
        "name": "category",
        "categoricalOptions": [
          {
            "id": "A",
            "label": "A very awesome category"
          },
          {
            "id": "B",
            "label": "A very busy category"
          },
          {
            "id": "C",
            "label": "A very complex category"
          }
        ]
      }
    ]
  }
}

Create/Add, Update, Delete by ID

Request

DELETE http://molgenis.mydomain.example/api/v2/<entity_name>/<entity_id>

Batch add/create

To create/add a list of entities into a collection you can POST the 'entities' parameter to a collection:

Request

POST http://molgenis.mydomain.example/api/v2/person
Content-Type: application/json

{entities: [
{
    "age": "101",
    "driverslicence": true
},
{
    "age": "102",
    "driverslicence": true
}
]}

Response

201 Created

Body

{
    location: "/api/v2/Person?q=id=in=("1","2")"
    resources: [{
        href: "/api/v2/Person/1"
    },
    {
        href: "/api/v2/Person/2"
    }]
}

* href: "/api/v2/Person/2" returns a created resource
* location: /api/v2/person/?q=id=in=(1,2) returns all created resources

Batch update

To batch update a list of entities of a collection you can PUT the 'entities' parameter to a collection:

Request

PUT http://molgenis.mydomain.example/api/v2/person
Content-Type: application/json

{entities: [
{
    "id": 1,
    "age": "11",
    "driverslicence": true
},
{
    "id": 2,
    "age": "12",
    "driverslicence": true
}
]}

Response

204 No Content

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

DELETE http://molgenis.mydomain.example/api/v2/person
Content-Type: application/json

{
    entityIds: ["person0", "person1"]
}

Response

204 No Content

Body

{
    location: "/api/v2/Person?q=id=in=("1","2")"
    resources: [{
        href: "/api/v2/Person/1"
    },
    {
        href: "/api/v2/Person/2"
    }]
}

One value

If you only want to change one attribute without needing to provide all other attributes:

Request

PUT http://molgenis.mydomain.example/api/v2/person/age
Content-Type: application/json

{entities: [
{
    "id": 1,
    "age": "1"
},
{
    "id": 2,
    "age": "2"
}
]}

Response

204 No Content
PreviousREST api v1NextFiles api

Last updated