Using RESTful web services

Here we will explain a quick tutorial on how to use the OpenCGA Web Services. It assumes that you went succesfully through the Download and Installation process.

If you access the URL http://localhost:8080/opencga in your browser, you should see a Swagger page where the REST API is listed. You can use it directly or use it programmatically using GET and POST methods of HTTP. Here we will describe the programmatic access, since the Swagger page already guides you on what are the required parameters and other details. The next example is equally valid for both usages, though.

Indexing a VCF

As described in Indexing Variant Data, you have to create a user to log in with, create a project and a study, and then you will be able to upload a VCF file, index it and do queries on it.

To create an example user, request this URL:

http://localhost:8080/opencga/rest/users/create?userId=myuser&name=myname&[email protected]&organization=my organization&password=mypass

and you will receive something like:

result": [
    {
        "id": "myuser",
        "name": "myname",
        "email": "[email protected]",
        "password": "mypass",
        "organization": "my organization",
        "role": "USER",
        "status": "",
        "lastActivity": "20150819165007169",
        "diskUsage": -1,
        "diskQuota": -1,
        "projects": [ ],
        "tools": [ ],
        "sessions": [ ],
        "configs": { },
        "attributes": { }
    }
]

From now on, you must log in to manage your user:

http://localhost:8080/opencga/rest/users/myuser/login?password=mypass

and you will receive a sessionId that you have to use in the next requests:

"result": [
    {
        "sessionId": "FLAtBLi5HOzkwJoS9hLR",
        "userId": "myuser"
    }
]

To create a project and a study:

http://localhost:8080/opencga/rest/projects/create?userId=myuser&name=project name&alias=myproject&description=This is my project&organization=This is my project organization&sid=FLAtBLi3HOzkwJoS9hLR
http://localhost:8080/opencga/rest/studies/create?projectId=myuser@myproject&name=my study name&alias=mystudy&sid

result": [
{
    "id": 1553,
    "name": "project name",
    "alias": "myproject",
    "creationDate": "20150819165054",
    "description": "This is my project",
    "organization": "This is my project organization",
    "status": "",
    "diskUsage": 0,
    "acl": [
            {
                "userId": "*",
                "read": false,
                "write": false,
                "execute": false,
                "delete": false
            }
        ],
        "studies": [ ],
        "attributes": { }
    }
]

result": [
    {
        "id": 1554,
        "name": "my study name",
        "alias": "mystudy",
        "type": "CASE_CONTROL",
        "creatorId": "myuser",
        "creationDate": "20150819165403",
        "description": "",
        "status": "active",
        "lastActivity": "20150819165403",
        "diskUsage": 0,
        "cipher": "none",
        "acl": [ ],
        "experiments": [ ],
        "files": [ ],
        "jobs": [ ],
        "samples": [ ],
        "datasets": [ ],
        "cohorts": [ ],
        "variableSets": [ ],
        "stats": { },
        "attributes": { }
    }
]