Skip to content

Introduction to API

This is a quick "how-to" for beginners using python scripts or application programming interfaces (APIs) to interface with the DB. The general idea of DB APIs is to

  • format your local data (csv, txt, header file, etc.) and additional information needed for your DB interaction (serial number, test run number, timestamp, etc.) to a common json format (DTOin);
  • call a database interface function (uuCmd) with the DTOin as the input to perform the DB action.

This page will introduce how to use the uuCmd documentation to create the DTOin templates needed for different DB action. A simple example of executing uuCmds is shown in itkdb installation page.

Database uuCmd

The list of uuCmd can be found in the PDB API documentation. Here, we will go over a few key points of how to use these documentation to make a correct DTOin.

  • uuCmd name: name of the DB action, e.g. getComponent, uploadTestRunResults
  • uuAppProfiles of uuCommand: the authority levels who can use this uuCmd (if you do not have the marked authority, you will get an error using this uuCmd)
  • Input (dtoIn): the json input with the equivalent python dictionary format and can contain lists and sub-dictionary. The "keys" are case-sensitive and needs to be used as is given in the documentation (e.g. alternativeIdentifier, serialNumber); the users need to provide the "value" for each key
  • Validation (dtoInType): required keys and values are follwed by ".isRequired()"; data format is given for each key (e.g. string, boolean, options given in a list, etc)
  • Output (dtoOut): the output after executing the DB action in a json (python dictionary format); if one needs information from the output, it can be accessed by using the keys listed here
  • Error List: error code and error message to be printed if DB action failed. When reporting error to the ticketing system or the mailing list, we strongly encourage to paste the error message in order for a quicker bug fix.

Below we provide a few tips to make the process of creating the DTOin easier. Firt is explanation of several common DTO keys; next is some existing DTOin template you can find in the DB.

Common DTOin keys

  1. code of a specific component

    component: "...", // component identification, it can be either code or ATLAS Serial Number

    While code is returned using several uuCmd, such as getComponent, code can be easily found in the url link. E.g.

    https://uuapp-dev.plus4u.net/ucl-itkpd-maing01/dcb3f6d1f130482581ba1e7bbe34413c/componentView?code=2c93ed5610149b0c839ec9f56ade22ac

    The code here is given after "code=", and here it is: 2c93ed5610149b0c839ec9f56ade22ac.

    Similarly applies to many other DB identifiers (e.g. component type id, test type id, etc.).

DTOin template

For uploadTestRunResults, there is available DTOin template given for each test type. The user can see the template by clicking "Show Dto Sample" at the test type definition page. See the example below for the sensor current stability test. Dto Sample for test run upload

Examples of posting Information to PDB

Code is King

To input and access information from a predefined set of options (e.g. componentType, institution, stage) in the PDB the relevant parameter code must be used.

Codes can be found using the Unicorn webApp or using listing API commands like listComponentTypes, listTestTypes, listInstitutions. See PDB API documentaion details and more examples.

Querying Example

To a list of components currently at an institution (using the API listComponents command) the uploaded json must include the:

1
'currentLocation': "GL"
  • here "GL" is the instiution code for Glasgow.

Registration examples

To register a module component for the pixels project (using the API registerComponent command) the uploaded json must include:

1
2
'project': "P",
'componentType': "MODULE"
  • here "P" is the project code for pixels and "MODULE" is the componentType code.

To get an upload a testRun for bow measurements for strips modules (using the API uploadTestRunResults command) the json must include:

1
2
3
'project': "S",
'componentType': "MODULE"
'testType': "MODULE_BOW"

  • here "S" is the project code for strips, "MODULE" is the componentType code and "BOW" is the testType code. All parameter information sent to the PDB must also be specified using codes, e.g. "BOW", "TEMPERATURE", "I_500".

  • NB codes are usually uppercase, though there are exceptions. Please check the specific data-strucuture.