Filtering List Resources

When submitting a GET request to certain REST API resources (also known as list resources), the system returns a list of records. For example, submitting a GET request to the samples resource returns a list of all submitted samples stored in the system. Depending on the resource being used, use various query parameters to filter the records based on certain criteria. For more information about the parameters that are available, refer to the reference documentation for the desired resource.

To filter a list, the resource and parameter must be separated with a question mark (?). The parameter and the value you want to base the query on must be separated with an equal sign (=).

When filtering a list of artifacts, combine parameters within the same query statement. You can also repeat certain parameters, specifying a new value with each occurrence of the parameter.

The first parameter must be preceded with a question mark (?). Add additional parameters by separating each parameter with an ampersand (&).

Repeating a parameter with new values:

Combining parameters:

When combining or repeating parameters, each record returned matches one of the parameter values, or all the parameter values, depending on the usage:

• If the query statement contains multiple values for the same parameter, the ampersands are treated as an OR.
• If the query statement contains values for multiple parameters, the ampersands are treated as an AND.

For example, if a project LIMS ID and a process type are provided as parameters, the system returns only the files that match both the project LIMS ID and the process type. To see the files that match the project LIMS ID or the process type, issue two separate GET requests and combine the results.

• /api/v2/processes—This URI returns all processes run in the system.
• /api/v2/processes?type=MALDI—This URI returns all MALDI processes run in the system.
• /api/v2/processes?type=Sample Prepandtype=MALDI—This URI returns all MALDI or Sample Prep processes run in the system.
• /api/v2/containers—This URI returns all containers in the system.
• /api/v2/containers?type=Tube—This URI returns all tubes in the system.
• /api/v2/containers?type=Tubeandname=27-111andname=27-112—This URI returns the tubes in the system that are named 27-111 OR 27-112.

Certain resources include the last-modified query parameter.

When used, the system displays only the results that have been modified because the last-modified date. The last-modified date is represented in ISO 8601 Complete date including hours, minutes, and seconds format: YYYY-MM-DDThh:mm:ssTZD.

Lists of records are often large, spanning multiple pages. Many list resources include parameters that are used to work with paginated results.

Certain resources include parameters that can be used to filter the results displayed based on UDF information that is associated with the results:

• udf.UDFNAME[.OPERATOR]=UDFVALUE—This parameter filters the results based on a specified value for a specified UDF. Any item that contains the value for the UDF is returned, unless parameters include an optional operator filter ( [.OPERATOR] in the expression provided). The lowercase filter operators of min or max are described later.
• udt.name=UDTNAME—This parameter filters the results based on a specified UDT. Any item that has the UDT selected is returned.
• udt.UDTNAME.UDFNAME[.OPERATOR]=UDFVALUE—This parameter filters the results based on a specified value for a specified UDF that resides within a specified UDT. Any item that contains the value for the UDF is returned, unless parameters include an optional operator filter ( [.OPERATOR] in the expression provided). The lowercase filter operators of min or max are described later.

To filter results using UDF information, use the following query structure:

To filter results using the name of a UDT, use the following query structure:

To filter results using UDF information that is part of a specific UDT, use the following query structure:

When filtering lists and using date or numeric UDF or UDT values, use operators to restrict a query. The following operators are supported:

• .min—This operator displays results that are greater than or equal to the specified value.
• .max—This operator displays results that are less than or equal to the specified value.

Examples:

• /api/v2/processes?type=Sample Prepandudt.name=Plasma—This URI returns all Sample Prep processes run in the system that have the Plasma UDT selected.
• /api/v2/processes?type=Sample Prepandudt.Plasma.Platelet Count.min=50—This URI returns all Sample Prep processes that have a UDF named Platelet Count with a value of 50 or greater, within a UDT named Plasma.
• /api/v2/processes?type=Sample Prepandudf.Sample=Serumandudf.Sample=Tissue—This URI returns all Sample Prep processes that have a UDF named Sample with a value of Serum OR a UDF named Sample with a value of Tissue.More examples of filtering exist in the Cookbook.

For more examples of filtering, see the About the Cookbook.

When filtering with UDT or UDF parameters, all special characters in the parameter string must be URL encoded. The Pipe ( | ) or the URL-encoded pipe ( ) cannot be used.

When filtering on a UDF that is configured as a Multiline Text UDF, if a value contains a hard return, the value must include the URL-encoded line feed () at the appropriate location. Depending on how API requests are issued (via a browser or a script), spaces in names or values may require URL encoding, and trailing spaces in a name or value always require encoding. For example, for results to be returned, ‘name ‘ requires ‘name’.