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