Topics

• Overview
• Calling API Actions from Client Applications and Scripts
• Query Controller API Actions
• Project Controller API Actions
• Assay Controller API Actions
• Troubleshooting Tips

Overview

If a client library does not yet exist for the language of your choice, you can interact with a LabKey Server through HTTP requests from the client-side language of your source (e.g., PHP). However, using a client library is strongly recommended.

The HTTP Interface exposes a set of URLs (or "links") that return raw data instead of nicely-formatted HTML (or "web") pages. These may be called from any program capable of making an HTTP request and decoding the JSON format used for the response (e.g., C++, C#, etc.).

This document describes the API actions that can be used by HTTP requests, detailing their URLs, inputs and outputs. For information on using the JavaScript helper objects within web pages, see JavaScript API. For an example of using the HTTP Interface from Perl, see Example: Access APIs from Perl.

Calling API Actions from Client Applications and Scripts

The API actions documented below may be used by any client application or script capable of making an HTTP request and handling the response. Consult your programming language’s or operating environment’s documentation for information on how to submit an HTTP request and process the response. Most languages include support classes that make this rather simple.

Several actions accept or return information in the JavaScript Object Notation (JSON) format, which is widely supported in most modern programming languages. See http://json.org for information on the format, and to obtain libraries/plug-ins for most languages.

Most of the API actions require the user to be logged in so that the correct permissions can be evaluated. Therefore, client applications and scripts must first make an HTTP POST request to the LabKey login handler. To login, do an HTTP POST request for the following URL:

http://<MyServer>/<LabkeyRoot>/login/login.post

where "<MyServer>" is the name of your server and "<LabkeyRoot>" is the name of your server's context path ('labkey' by default).

Set the content-type to “application/x-www-form-urlencoded” and in the post body, include the following parameters:

email=<UserEmailAddress>&password=<UserPassword>

In the resulting HTTP response, a cookie by the name of “JSESSIONID” will be returned. This cookie must be passed in all subsequent HTTP requests. In many runtime environments, the HTTP support libraries will do this automatically. Note that the HTTP response from a login request will be a redirect to the Home project’s portal page (response code of 301). The application or script can ignore this redirect and simply request the desired API actions, passing the returned JSESSIONID cookie.

Alternatively, clients may use HTTP basic authentication. See http://en.wikipedia.org/wiki/Basic_authentication_scheme for details on the HTTP headers to include, and how to encode the user name and password. The "realm" can be set to any string, as the LabKey server does not support the creation of multiple basic authentication realms.

Note that basic authentication is considered less secure as it passes the user name/password information with each request, but if the client uses the HTTPS protocol, the headers will be encrypted.

The following sections document the supported API actions in the current release of LabKey server.

For further examples of these action in use, plus a tool for experimenting with "Get" and "Post" parameters, see Examples: Controller Actions

Query Controller API Actions

selectRows Action

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

Example URL:

http://<MyServer>/labkey/query/<MyProj>/selectRows.api?schemaName=lists&query.queryName=my%20list

where "<MyServer>" and "<MyProj>" are placeholders for your server and project names.

HTTP Method: GET

Parameters: Essentially, anything you see on a query string for an existing query grid is legal for this action.

The following table describes the basic set of parameters.

Response Format:

The response can be parsed into an object using any one of the many JSON parsers available via http://json.org.

The response object contains four top-level properties:

• metaData
• columnModel
• rows
• rowCount

columnModel: The columnModel contains information about how one may interact with the columns within a user interface. This format is generated to match the requirements of the Ext grid component. See Ext.grid.ColumnModel for further information.

rows: This property contains an array of rows, each of which is a sub-element/object containing a property per column.

rowCount: This property indicates the number of total rows that could be returned by the query, which may be more than the number of objects in the rows array if the client supplied a value for the query.maxRows or query.offset parameters. This value is useful for clients that wish to display paging UI, such as the Ext grid.

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.

Example URL:

http://<MyServer>/labkey/query/<MyProj>/updateRows.api

HTTP Method: POST

POST body: The post body should contain JSON in the following format:

{"schemaName": "lists",
  "queryName": "Names",
  "rows": [
    {"Key": 5,
     "FirstName": "Dave",
     "LastName": "Stearns"}
  ]
}

Content-Type Header: Because the post body is JSON and not HTML form values, you must include the 'Content-Type' HTTP header set to 'application/json' so that the server knows how to parse the incoming information.

The schameName and queryName properties should match a valid schema/query name, and the rows array may contain any number of rows. Each row must include its primary key value as one of the properties, otherwise, the update will fail.

By default, all updates are transacted together (meaning that they all succeed or they all fail). To override this behavior, include a “transacted”: false property at the top level. If 'transacted' is set to 'false,' updates are not automic and partial updates may occur if an error occurs mid-transaction. For example, if some rows have been updated and an update produces an error, the rows that have been updated before the error will still be updated.

The response from this action, as well as the insertRows and deleteRows actions, will contain JSON in the following format:

{ "schemaName": "lists",
  "queryName": "Names",
  "command": "update",
  "rowsAffected": 1,
  "rows": [
    {"Key": 5,
     "FirstName": "Dave",
     "LastName": "Stearns"}
  ]
}

The response can be parsed into an object using any one of the many JSON parsers available via http://json.org.

The response object will contain five properties:

• schemaName
• queryName
• command
• rowsAffected
• rows

The rowsAffected property will indicate the number of rows affected by the API action. This will typically be the same number of rows passed in the HTTP request.

The rows property contains an array of row objects corresponding to the rows updated, inserted, or deleted, in the same order as the rows supplied in the request. However, the field values may have been modified by server-side logic, such as LabKey's automatic tracking feature (which automatically maintains columns with certain names, such as "Created", "CreatedBy", "Modified", "ModifiedBy", etc.), or database triggers and default expressions.

insertRows Action

Example URL:

http://<MyServer>/labkey/query/<MyProj>/insertRows.api

HTTP Method: POST

Content-Type Header: Because the post body is JSON and not HTML form values, you must include the 'Content-Type' HTTP header set to 'application/json' so that the server knows how to parse the incoming information.

The post body for insertRows should look the same as updateRows, except that primary key values for new rows need not be supplied if the primary key columns are auto-increment.

deleteRows Action

Example URL:

http://<MyServer>/labkey/query/<MyProj>/deleteRows.api

HTTP Method: POST

Content-Type Header: Because the post body is JSON and not HTML form values, you must include the 'Content-Type' HTTP header set to 'application/json' so that the server knows how to parse the incoming information.

The post body for deleteRows should look the same as updateRows, except that the client need only supply the primary key values for the row. All other row data will be ignored.

executeSql Action

This action allows clients to execute SQL.

Example URL:

http://<MyServer>/labkey/query/<MyProj>/executeSql.api

HTTP Method: POST

Post Body:

The post body should be a JSON-encoded object with two properties: schemaName and sql. Example:

{
    schemaName: 'study',
    sql: 'select MyDataset.foo, MyDataset.bar from MyDataset'
}

The response comes back in exactly the same shape as the selectRows action, which is described at the beginning of the Query Controller API Actions section of this page.

Project Controller API Actions

getWebPart Action

The getWebPart action allows the client to obtain the HTML for any web part, suitable for placement into a <div> defined within the current HTML page.

Example URL:

http://<MyServer>/labkey/project/<MyProj>/getWebPart.api?webpart.name=Wiki&name=home

HTTP Method: GET

Parameters: The “webpart.name” parameter should be the name of a web part available within the specified container. Look at the Select Web Part drop-down menu for the valid form of any web part name.

All other parameters will be passed to the chosen web part for configuration. For example, the Wiki web part can accept a “name” parameter, indicating the wiki page name to display. Note that this is the page name, not the page title (which is typically more verbose).

Assay Controller API Actions

assayList Action

The assayList action allows the client to obtain a list of assay definitions for a given folder. This list includes all assays visible to the folder, including those defined at the folder and project level.

Example URL:

http://<MyServer>/labkey/assay/<MyProj>/assayList.api

HTTP Method: GET

Parameters: None

Return value: Returns an array of assay definition descriptors.

Assay definition descriptor has the following properties:

Domain property objects have the following properties:

Troubleshooting Tips

If you hit an error, here are a few "obvious" things to check:

Spaces in Parameter Names. If the name of any parameter used in the URL contains a space, you will need to use "%20" or "+" instead of the space.

Controller Names: "project" vs. "query" vs "assay." Make sure your URL uses the controller name appropriate for your chosen action. Different actions are provided by different controllers. For example, the "assay" controller provides the assay API actions while the "project" controller provides the web part APIs.

Container Names. Different containers (projects and folders) provide different schemas, queries and grid views. Make sure to reference the correct container for your query (and thus your data) when executing an action.

Capitalization. The parameters schemaName, queryName and viewName are case sensitive.