API Reference

Test Results

Posting Results

To POST results to MFTestBench, use the /api/v1/testbench/results API endpoint:

$ curl -X POST -d '
    {
        "test_results": {
            "product_name": "08-0001-01",
            "sku": "08-0001-01",
            "status": "PASS",
            "results": {
                "temperature": 32.2
            }
        }
    }' https://api.macrofab.com/api/v1/testbench/results?apikey=<apikey>

There are several "top-level" keys that are natively supported by MFTestBench:

  • device_id
  • product_name
  • product_sku
  • product_revision
  • batch
  • serial_number
  • location_id
  • station
  • status (required)
  • results (required)
  • created

The data within results can be whatever the user wants, as long as it's valid JSON. It is recommended to avoid arrays, however, purely because it can be difficult to concoct Lucene and JSON queries that can walk arrays.

If, like in the above case, a device ID or serial number was not provided, a new device will be created. If a device ID or serial number is provided, then the test results will be appended to the existing device.

The service then returns the new or updated device, along with all of its test records.

{
    "batch": null,
    "counter": null,
    "device_created": "2024-05-13 16:11:36.479405",
    "device_id": "jg502a41",
    "itar_restricted": null,
    "organization_id": "knvcnk",
    "organization_name": "MacroFab",
    "product_name": "08-0001-01",
    "product_revision": null,
    "product_sku": null,
    "results": [
        {
            "created": "2024-05-13T16:11:36.482014",
            "location_id": null,
            "result": {
                "temperature": 32
            },
            "station": null,
            "status": "PASS",
            "test_result_id": "40w3db4g",
            "user_id": "m0digm"
        }
    ],
    "serial_number": null
}

Setting Attributes

Users might want their product SKUs to have attributes. For example, it might be useful to tag a SKU as being ITAR restricted, or to set some attributes that define the unit's typical operating parameters. One can use the /api/v1/testbench/sku/<sku>/attributes endpoint to POST a JSON document -- again, with arbitrary contents -- that will be returned in a sku_attributes section of later test result queries and searches. See the API documentation for more information.

If the key itar_restricted is present at the top level of the attributes, that will be used to automatically filter results from users who do not have ITAR permissions.

Quering Results

There are two paths for querying test results:

  1. Using the /api/v1/testbench/results endpoint with filters.
  2. Using the /api/v1/testbench/results/search endpoint with Lucene-based query strings.

Filtering

The following filters are supported as standard query parameters:

  • device_id
  • product_name
  • product_sku
  • product_revision
  • serial_number
  • station
  • status
  • start_time
  • end_time

The endpoint will return 50 rows by default. Pagination can be achieved through the following two parameters:

  • offset
  • limit

Additionally, the only_latest=1 query parameter can be supplied if you want to see only the latest test result for a device instead of an array of all of its test results.

Searching

Users can execute more complicated Lucene-style queries using the /api/v1/testbench/results/search endpoint. Instead of the list of filters allowed in the /api/v1/testbench/results endpoint, all fields can be searched using dot notation.

Let's use this result as an example:

{
    "batch": null,
    "counter": null,
    "device_created": "2024-01-26 00:00:58.522728",
    "device_id": "erv87bq0",
    "itar_restricted": null,
    "organization_id": "m73h8m",
    "organization_name": "MacroFab",
    "product_name": "Test Product",
    "product_revision": null,
    "product_sku": "MF-TEST-0008",
    "results": [
        {
            "created": "2024-01-26T00:00:58.524677",
            "location_id": null,
            "result": {
                "device_type": "battery",
                "grmsx": "4.1",
                "grmsy": "2.3",
                "grmsz": "8.9",
                "mac_address": "12:6a:4a:2d:35:21",
                "software_version": "1.5.0",
                "temperature": "23",
                "test_type": "initial"
            },
            "station": null,
            "status": "PASS",
            "test_result_id": "erv87bq0",
            "user_id": "m58hrk"
        }
    ],
    "serial_number": null
}

One can query for the grsmx value in the results using the following query:

$ curl -X POST -d '
    {
        "test_results_search": {
            "query": "product_name:\"Test Product\" AND status:PASS AND result.grmsx:4.1"
        }
    }' https://api.macrofab.com/api/v1/testbench/results/search?apikey=<apikey>

Note that even though the status is a per-result variable, since it's a "reserved" term it is not required to prefix it with result. The result prefix is only needed for descending down into the custom test data JSON.