Table of contents

Overview

The Testify API allows you to send sensor data to Testify so that it can be used as part of a checklist. It is designed for companies trying to automate some of the checks in their Testify checklists.

Modes of operation

There are 2 ways to send data to Testify:

• Registered Devices can send data to Testify at any time and it will be saved by Testify in case it is needed by a checklist. Any mechanism to send HTTP requests can be used here.

• Public Devices need to be publicly accessible, so that Testify can send a request to it in case its value is needed by a checklist. Any HTTP server with JSON responses can be used here.

Open

Available check types

Regardless if you use Registered Devices or Public Devices, you will need to know what check type you are sending or providing to Testify:

Notice that for FileChecks and PhotoChecks, Testify needs to be provided with the MIME type of the photo or the file that was sent to them. This is necessary so that Testify can display the file or photo properly.

Allowed MIME types for FileChecks

Allowed MIME types for PhotoChecks

Further reading

• If you are interested in Registered Devices, look into Registered Devices for general information or Registered Device Examples for real world examples with code in some popular programming languages.

• If you are interested in Public Devices, look into Public Devices for general information or Public Device Examples for real world examples with code in some popular programming languages.

Public Devices

Public Devices need to be publicly accessible, so that Testify can send a request to it in case its value is needed by a checklist.

Technology

Any HTTP server with JSON responses can be used here. This means that any public API like weather APIs and others can act as Public Devices.

The structure of this JSON response can be very flexible, however it must be possible to decide which part of the JSON response (e.g. which property) should be used as a check result within Testify by specifying a JSON Path (see chapter "JSON paths").

Important: Make sure that this API is reachable on the Internet (e.g. have a public IP address or domain). Otherwise Testify will not be able to access it. The easiest way to test this is to try accessing this API with a different internet access than the one of your company (e.g. your private mobile phone).

Samples in some commonly used programming languages and frameworks can be found in Public Device Examples.

Connecting the API to Testify

Wheather you created your own API or use an existing one, you have to connect it to Testify . This can be done in the Testify web interface in Devices. If you create a Public Device there, you will need to provide:

• URL: url of the API

• HTTP method: what HTTP method should Testify use to make the request to the API. This is GET in most cases.

• HTTP headers: any HTTP headers that Testify should send along with the request. This might be needed for an API-key.

• Check type: what type of data you want to make accessible to Testify. For a list of available check types visit Overview.

For any check other than FileChecks or PhotoChecks :

• JSON path: used to locate the exact value you want to provide to Testify. For more information see "Using JSON paths" below.

If you selected FileCheck or PhotoCheck, you have to use one of the following options instead of the JSON path mentioned above:

• MIME type: enter the MIME type of the file or photo you want to send manually

• JSON path to value: JSON path to the value you want to provide to Testify

  OR

• JSON path to MIME type: JSON path to the MIME type

• JSON path to value: JSON path to the value you want to provide to Testify

  OR (for FileChecksonly)

• JSON path to file array: JSON path to the array of FileChecks. This array needs to have the following structure:

  [ { "value": YOUR_BASE64_STRING, "mimeType": YOUR_MIME_TYPE }, // other array elements here ]

Using JSON paths

JSON paths are used to extract a specific value from some JSON.

When accessing information from a public device, this JSON path tells Testify what information in the HTTP response it should use.

For example, if we have the following HTTP response:

And we want to get the value iPhone we can use the following JSON path:

In the simplest case you might have a response like this:

And we would get the value 3.14159 like this:

For more information on this concept visit https://jsonpath.com/ .

Public Device Examples

The purpose of this example is to setup a HTTP server that returns "Hello world". This server is then connected to Testify.

C#

Note:

• This example is done using a C# Minimal API for simplicity, but similar functionality can also be achieved when using a more traditional ASP.NET API with controllers.

Python

Note:

• This example uses flask which is a lightweight web framework. It can be installed with pip install Flask.

• The last if is unnecessary if the python script is run with the command flask run. However, this takes more steps to setup which is why it hasn't been done here. For more information visit https://www.twilio.com/blog/how-run-flask-application . The script above works by simply running py FILENAME.py as you would expect.

Javascript

Note:

• This example uses express, which can be installed with npm install express.

Connecting the API to Testify

In order to make the "Hello World"-API that we created above accessible to Testify, we need to create a Public Device in the Testify web interface with the following options:

• URL: depends on where you run your server

• HTTP method: GET

• HTTP headers: None

• Check type: TextCheck

• JSON path: $.text

Other check types

Depending on the check type, you need to send to provide data in a different format.

• See Overview for a list of all check types and the format they require.

• See other check types in Registered Device Examples for examples in C#, Python and Javascript.

Registered Devices

Registered Devices can send data to Testify at any time and it will be saved by Testify in case it is needed by a checklist.

Technology

The API is a public HTTP endpoint that accepts JSON data. Therefore any programming or scripting language capable of sending HTTP requests can be used to send data to the API.

Samples in some commonly used programming languages can be found in Registered Device Examples.

Access

The API is accessible at the following URL: https://externaldatastore.azurewebsites.net/api/device/CHECK_TYPE where CHECK_TYPE is the CheckType you want to send data for.

Authentication

You must include a deviceId with every API request. This deviceId can be created with the Testify web interface in Devices.

In Testify this can be created under Administration -> Equipment Types -> Equipment in the section "External Devices".

Open

Request structure

There are 3 ways to add the deviceId to your HTTP request. Therefore, there are 3 different ways your HTTP request might look.

deviceId in Query-String

Add ?deviceId=YOUR_DEVICE_ID to the end of your request url.

deviceId as a HTTP-Header

Add a deviceId HTTP-Header with the value of YOUR_DEVICE_ID.

deviceId in the HTTP-Body

Add a deviceId property to the JSON in the HTTP body.

Note:

• value is the actual value that you want to send to the API. This varies depending on the check type.

Custom timestamp

By default Testify uses the timestamp of the HTTP request as a creationDate. However, if the time you get data from your sensor and the time you send it to the API vary, you might consider adding a creationDate manually.

Adding MIME types to the Request

For FileChecks and PhotoChecks you need to add the MIME type to the request. There are 2 ways to do that:

With an additional property

The easiest way is to add the property valueMimeType to the http request and specify the appropriate MIME type there.

With a data URL

Another way to add the MIME type to the request is to use a data URL instead of standard base64-string.

Data urls are essentially base64-strings with MIME-types attached to them. For example:

So with this data URL, your request could look like this:

Note:

• CHECK_TYPE is either FileCheck or PhotoCheck

• YOUR_BASE64_STRING is the base64-representation of the file or image you want to send

• YOUR_MIME_TYPE is one of the allowed MIME types listed in Overview

Response status codes

After sending data to the Testify API, you can look at the HTTP status code of the response to determine wheater your request was successful or failed. If a request failed, status codes can provide additional information on why it failed.

Registered Device Examples

This simple example sends the string "Hello world" to the Testify API as a TextCheck.

C#

Note:

• The HttpClient should only be instantiated once (don't create a new one if you have to make multiple requests).

• client.PostAsync is an asynchronous method which allows other code to run while we wait for the response. However, here we want to work with the result immidiately after the POST request, which is why await is used to force the program to wait for the response. In other scenarios (e.g. when having multiple API calls), removing await can lead to better performance.

Python

Note:

• The library requests has to be installed for this to work. It can be installed using pip install requests.

Javascript

Note:

• When Javascript is run in a browser fetch is available by default. However, if we want to run it in Node.js we have to install it first by running npm install node-fetch and importing it at the top of our file with import fetch from "node-fetch".

• fetch returns a Promise, which can be handled with then like in the example above or with async/await. For more information visit https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Statements/async_function .

Curl

Note for all of the examples above:

• YOUR_DEVICE_ID needs to be replaced with your specific deviceId. Information on how to get this can be found at [Authentication in Registered Devices](Registered Devices.md).

Other authentication methods

If you don't want to add your deviceId as a query parameter at the end of the url like in the example above, you can also use one of the following two approaches:

deviceId as a HTTP-Header

deviceId is added as a HTTP header with the value of YOUR_DEVICE_ID.

deviceId in the HTTP-Body

deviceId is added in the payload of the HTTP request.

Other check types

Depending on the check type, the value you send to the API has to be of a certain type (see Available check types in Overview). Here are some examples using all the different check types in different programming languages.

TextCheck

NumericCheck

LogicCheck

SingleChoiceCheck

Here you need to provide the GUID of the choice from the single choice check that we want to select.

MultipleChoiceCheck

Here you need to provide the GUID of the choices from the multiple choice check that we want to select.

TestobjectSelection

Here you need to provide the GUID of the test objects you want to select.

TimeCheck

If you use language that doesn't allow you to create a Timeonly datatype (Javascript) or where the serializer doesn't support the Timeonly type yet (C#), you have 2 options:

• Create a normal Date (Javascript) or DateTime (C#) object and enter random values for the date (the date will be ignored by the Testify API).

• Send a string representation of the time you want.

DateCheck

FileCheck

FileChecks are somewhat different from other checks:

• You can send multiple files with one request (notice that a list of objects is used).

• You have to provide a mime type for every file. For a list of all allowed mime types visit Allowed MIME types for FileChecks.

PhotoCheck

Photo are somewhat different from other checks, as you have to provide a mime type for every photo you send to the API. For a list of all allowed mime types visit Allowed MIME types for PhotoChecks.

Notice that we don't use a list here like we do with FileChecks.