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 DB 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.