Overview

This page provides a supplemental set of examples to help you get started using the HTTP Interface.

Topics:

• The API Test Tool. Use the API Test Tool to perform HTTP "Get" and "Post" operations.
• Define a List. Design and populate a List for use in testing the Action APIs.
• Query Controller API Actions:
• getQuery Action
• updateRows Action
• insertRows Action
• deleteRows Action
• Project Controller API Actions:
• getWebPart Action
• Assay Controller API Actions:
• assayList Action

The API Test Tool

Please note that only admins have access to the API Test Tool.

To reach the test screen for the HTTP Interface, enter the following URL in your browser, substituting the name of your server for "<MyServer>" and the name of your project for "<MyProject>:"

http://<MyServer>/labkey/query/<MyProject>/apiTest.view?

Note that 'labkey' in this URL represents the default context path, but your server may be configured with a different context path. This documentation assumes that 'labkey' (the default) is your server's context path.

Define a List

You will need a query table that can be used to exercise the HTTP Interface. In this section, we create and populate a list to use as our demo query table.

Steps to design the list:

1. You will need to add the "Lists" web part via the Select Web Parts dropdown menu at the bottom of the page.
2. Click the "Manage Lists" link in the new Lists web part.
3. Click "Create a New List."
4. Name the list "API Test List" and retain default parameters.
5. Click "Create List."
6. Now add properties to this list by clicking the "edit fields" link.
7. Add two properties:
1. FirstName - a String
2. Age - an Integer
8. Click "Save"

• Name: API Test List
• Key Type: Auto-Increment Integer
• Key Name: Key
• Other fields in this list:
• FirstName: String
• Age: Integer

1. Click the "upload list items" link on the same page where you see the list definition.
2. Paste the information in the following table into the text box:

Your list is now populated. You can see the contents of the list by clicking the "view data" link on the list design page, or by clicking on the name of the list in the "Lists" web part on the project's portal page.

Query Controller API Actions: getQuery Action

The getQuery action may be used to obtain any data visible through LabKey’s standard query views.

Get Url:

/labkey/query/home/getQuery.api?schemaName=lists&query.queryName=API%20Test%20List

Response:

{
    "rows": [
        {
            "Key": 1,
            "FirstName": "A",
            "Age": 10
        },
        {
            "Key": 2,
            "FirstName": "B",
            "Age": 20
        }
    ],
    "metaData": {
        "totalProperty": "rowCount",
        "root": "rows",
        "fields": [
            {
                "type": "string",
                "name": "FirstName"
            },
            {
                "type": "int",
                "name": "Age"
            },
            {
                "type": "int",
                "name": "Key"
            }
        ],
        "id": "Key"
    },
    "rowCount": 2,
    "columnModel": [
        {
            "editable": true,
            "width": "200",
            "required": false,
            "hidden": false,
            "align": "left",
            "header": "First Name",
            "dataIndex": "FirstName",
            "sortable": true
        },
        {
            "editable": true,
            "width": "60",
            "required": false,
            "hidden": false,
            "align": "right",
            "header": "Age",
            "dataIndex": "Age",
            "sortable": true
        },
        {
            "editable": false,
            "width": "60",
            "required": true,
            "hidden": true,
            "align": "right",
            "header": "Key",
            "dataIndex": "Key",
            "sortable": true
        }
    ],
    "schemaName": "lists",
    "queryName": "API Test List"
}

Query Controller API Actions: updateRows Action

The updateRows action allows clients to update rows in a list or user-defined schema. This action may not be used to update rows returned from queries to other LabKey module schemas (e.g., ms1, ms2, flow, etc). To interact with data from those modules, use API actions in their respective controllers.

Post Url:

/labkey/query/home/updateRows.api?

Post Body:

{ "schemaName": "lists",
 "queryName": "API Test List",
 "rows": [
   {"Key": 1,
    "FirstName": "Z",
    "Age": "100"}]
}

Response:

{
    "keys": [1],
    "command": "update",
    "schemaName": "lists",
    "rowsAffected": 1,
    "queryName": "API Test List"
}

Result:

Query Controller API Actions: insertRows Action

Post Url:

/labkey/query/home/insertRows.api?

Post Body:

Note: The primary key values for new rows need not be supplied when the primary key columns are auto-increment.

{ "schemaName": "lists",
 "queryName": "API Test List",
 "rows": [
   {"FirstName": "C",
    "Age": "30"}]
}

Response:

{
    "keys": [3],
    "command": "insert",
    "schemaName": "lists",
    "rowsAffected": 1,
    "queryName": "API Test List"
}

Result:

Query Controller API Actions: deleteRows Action

Post Url:

/labkey/query/home/deleteRows.api?

Post Body:

Note: Only the primary key values for the row to delete are required.

{ "schemaName": "lists",
 "queryName": "API Test List",
 "rows": [
   {"Key": 3}]
}

Response:

{
    "keys": [3],
    "command": "delete",
    "schemaName": "lists",
    "rowsAffected": 1,
    "queryName": "API Test List"
}

Result:

Project Controller API Actions: getWebPart Action

NB: Remember, the URL of Project Controller actions includes "project" instead of "query," in contrast to the Query Controller Actions described above.

Lists. The web part we created when we created our list:

/labkey/project/<MyProject>/getWebPart.api?webpart.name=Lists

Wiki. Web parts can take the name of a particular page as a parameter, in this case the page named "home":

/labkey/project/<MyProject>/getWebPart.api?webpart.name=Wiki&name=home

Assay List. Some web part names have spaces. Remember, you can find the valid form of web part names in the Select Web Part drop-down menu. A web part with a space in its name:

/labkey/project/home/getWebPart.api?webpart.name=Assay%20List