Skip to main content
API docs by Redocly

Saimple Backend API v2 (2.0.0)

Download OpenAPI specification:Download

This page is a specification for the Saimple API.

Introduction

To test the following routes with the Swagger interface:

  • First, select the server which should handle the request. By default, the specification should access the development server.
    • Acquire an authentication token using the POST api/v2/authentification route, as it is required by most of our API routes. To do that, you'll need to:
      • Copy the access_token value from the JSON response.
      • Paste it in the popup field which appear when clicking the 'Authorise' button on the right on the page, before the routes descriptions.

Notes:

  • When using a local stack, be sure to use the same IP for Swagger and the accessed stack to avoid CORS issues.
    • In case you'd want to use the Curl script, you may have to add the --insecure option to avoid certificate issues.

Evaluations

Evaluations operations

Create an evaluation

Allows the launch and creation of an evaluation object

Notes:

  • Returns the created evaluation's identifier.
  • This can be used to track the evaluation status using the GET route.
  • The evaluation status can be : in progress, done or failed.
Authorizations:
bearerAuth
Request Body schema: application/json
analysisType
string
Default: "float"
Enum: "float" "double" "long double" "float128 | quad"

The floating type to use - 'float' being the fastest and less precise & 'float128' or 'quad' being the slowest yet the most precise

dataType
required
string
Enum: "Image" "TimeSeries"

Indicates whether the evaluation will handle Image or TimeSeries data. The image format supported are : *.png, *.jpg, *.jpeg, *.tiff, *.raw " The TimeSeries format supported are :.csv or .npy

description
string

Description of the evaluation

evaluationEngine
string
Default: "fae"
Enum: "fae" "fae_ts" "ad_svm"

The internal evaluation engine to select

force
boolean
Default: false

When enabled, the evaluation will ignore most errors or assert

input
required
string

The input data file to use for this evaluation, either its name or its resource identifier

inputDomain
Array of strings
model
required
string

The model to use for this evaluation, either its name or its resource identifier

name
required
string

The name associated with the evaluation

required
object
id
string
Default: ""

The evaluation Id. Normaly, should not be given here, as it will be generated

postProcessing
boolean
Default: true

This flag enable a post processing when the abstraction analysis is finished. Currently it only works for classifier. It should be set to false for other model

normalize
boolean
Default: true

When true, normalize from 0-255 to 0-1 - When set to false, use the input data as it is

outputSelected
string

The name of the tensor we want evaluated, can be used for early termination or to get to a point to restart from.

sanityCheck
string

Enable sanity control on the result, checking if the result from a concrete evaluation obtained through onnxruntime are contained in the abstract values obtained through the analysis. Possible values: none(disable), basic(check the final tensor), full(check all tensors after each operations)

sanityTreshold
string

The tolerance value for sanity check. Used as a relative value.

startAt
string

The layer where to start the analysis from in the model

Responses

Request samples

Content type
application/json
Example
{
  • "analysisType": "double",
  • "dataType": "Image",
  • "description": "This is an example description",
  • "evaluationEngine": "fae",
  • "input": "735e766c-25a6-11ec-92f1-0242ac1c0004",
  • "inputDomain": [
    ],
  • "model": "6c294368-25a6-11ec-a08e-0242ac1c0004",
  • "name": "Evaluation Example for an image classifier",
  • "noise": {
    },
  • "normalize": true
}

Response samples

Content type
application/json
{
  • "evalId": "571445e6-a245-11ed-bef3-02420a000089",
  • "message": "Evaluation succesfully launched, a unique id was automatically assigned to it"
}

Get all evaluations

Allows the query of all evaluations.

Notes:

  • This request wont return more than 100 evaluations at a time. The parameters are meant to be used to iterate with a pagination system.
  • A first query will return the number of matching evaluations in the nbResults field.
  • Use offset parameter to specify the index of the first evaluation to be returned.
  • The limit parameter define the number of evaluations returned *for each query, it must be in the interval [1;100].
Authorizations:
bearerAuth
query Parameters
filter (not implemented)
string

Query syntax to be defined later

limit
integer

The number of evaluation to be returned (must be >0 and <= 100, default to 100)

offset
integer

The starting index for selecting the evaluations returned

order_by
string

(not implemented, default to created:desc, query syntax to be defined later)

Responses

Response samples

Content type
application/json
{
  • "evaluations": [
    ],
  • "nbResults": 1
}

Delete all existing evaluations

Deletes ALL evaluations in the user workspace

Warning: The evaluations cannot be restored after calling this route!

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Evaluation successfully deleted"
}

Get evaluation details from its ID

Returns all available information for an evaluation.

Note: This route has side effects:

  • It will update the evaluation status by checking if the evaluation is finished or failed.
  • It is also currently used to detect the end of the abstract evaluation:
    • When it's done, it will implicitly triggers the relevant post-processing.
    • When all post-processing are done, the status is updated accordingly.
Authorizations:
bearerAuth
path Parameters
evalId
required
string
Example: 735e766c-25a6-11ec-92f1-0242ac1c0004

The evaluation's ID

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an existing evaluation

Deletes an existing evaluation by its ID

Notes:

  • This route will remove all ressources created during the evaluation and remove the corresponding reference for the model and input objects.
  • This operation cannot be undone.
  • It will not interrupt an evaluation and can only be used to remove the artifact and free disk space after the evaluation is finished.
Authorizations:
bearerAuth
path Parameters
evalId
required
string
Example: hopeful_morse

The evaluation's ID

Responses

Get evaluation raw relevance

Returns the execution trace for the given evaluation.

Notes: The trace can be requested while the evaluation is still running, it can be used to monitor its progression. The "out" and "err" parameters are captured from the evaluation engine stdout and stderr stream. The layers informations is formated by the engine. The parsedStandardError is a formatted version of the 'err' field and might not contains all informations

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The evaluation's ID

Responses

Response samples

Content type
application/json
{
  • "out": "string",
  • "err": "string",
  • "parsedStandardError": {
    },
  • "layersTrace": { }
}

Dominance

Retrieve dominance information

Get evaluation dominance

Gets dominance for a given evaluation byt its ID

Notes:

  • The dominance is mostly used with classifier models.
  • This route returns the range of possible values for each predictions.
  • It also gives the dominant class, if one of them was predicted with a class score always greater than all the others.
  • The dominance computation is applied directly on the abstract domain and not on the returned interval.
  • It's possible to have overlapping interval and to still obtain the dominance property.
Authorizations:
bearerAuth
path Parameters
evalId
required
string

The evaluation's ID

Responses

Response samples

Content type
application/json
{
  • "classes": [
    ]
}

Relevance

Retrieve relevance information

Get evaluation raw relevance

Returns the raw relevance for an evaluation by its ID.

Notes: The raw relevance is the relative importance of each entry on the final result.

Example: For a classifier processing a image in 100 x 100 x 3 size and producing 10 classes score, this route will:

  • return 10 x 100 x 100 x 3 values, which can be projected as 10 relevance image, one for each class,
  • then project those on the original image to observe the image feature relative impacts.
Authorizations:
bearerAuth
path Parameters
evalId
required
string

The evaluation's ID

query Parameters
svm_mode
string
Enum: "hog" "square"

Selection of the projection method of the relevance, either from an interpretation of the relevance computed from the hog edges or from the hog grid cell

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "shape": "(20, 30, 30)"
}

Inputs

Inputs data operations

Get the list of all inputs

Returns a list of all inputs

Notes: The pagination mechanism is not yet implemented.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "inputs": [
    ]
}

Upload a new input data file

Allows upload of a new input

Notes:

  • Input must have an extension in the following list:
    • .jpg / .jpeg
    • .png
    • .tif / .tiff
    • .raw
    • .csv
    • .npy
  • On success, the route returns the ID associated with the uploaded input
Authorizations:
bearerAuth
Request Body schema: multipart/form-data

An Image (.jpg, .jpeg, .png, .tif, .tiff .raw) or a TimeSeries (.csv, .npy) file to upload

filedata
object <binary>

The binary file of the input data

Responses

Request samples

Content type
multipart/form-data
Example
{
  "multipart/form-data": {
    "files": {
      "filedata": "<example_image.jpg>"
    },
    "reference": 5
  }
}

Response samples

Content type
application/json
{
  • "fileId": "111-222-333",
  • "fileName": "mnist_0.jpg"
}

Delete all existing inputs

Deletes all existing inputs data files for the current workspace

Notes: This operation cannot be reverted.

Authorizations:
bearerAuth

Responses

Get an input data file

Returns the specified input data file

Authorizations:
bearerAuth
path Parameters
fileId
required
string

The file identifier of the specified input

Responses

Response samples

Content type
application/octet-stream
filedata

Get an input metadata

Returns the specified input metadata

Authorizations:
bearerAuth
path Parameters
fileId
required
string

The file name or identifier of the specified input

Responses

Response samples

Content type
application/json
{
  • "id": "e4174818-be02-11eb-965e-65d067e2ea43",
  • "creationDate": "26/05/2021-11:15:19",
  • "originalFileName": "example_5.JPG",
  • "fileName": "e4174818-be02-11eb-965e-65d067e2ea43.jpg",
  • "format": "Image",
  • "evaluations": [ ]
}

Delete an existing input

Deletes the specified input and its data files

Note: The route itself allows the suppression of inputs that are being used by evaluations. This may render them inexploitable. The frontend application emits an alert and offers to delete the associated evaluations but not the API.

Authorizations:
bearerAuth
path Parameters
fileId
required
string

The file name or identifier of the specified input

Responses

Response samples

Content type
application/json
{
  • "message": "Error, too many files found with name : mnist_input.png",
  • "locations": [
    ],
  • "matching_ids": [
    ]
}

Models

Models operations

Upload a new model file

Allows the upload of a compatible neural network model (*.h5, *.onnx) or svm (.npy)

Notes: On reception of the model, the backend will try to parse it to extract the model expected input shape. On reception, the model the backend will check is the same file already existe in the user workspace to avoid duplication. If the model already exist, the api return a http 200 response with the existing file id

Authorizations:
bearerAuth
Request Body schema: multipart/form-data

The model file to upload

model
object <binary>

Responses

Request samples

Content type
multipart/form-data
{
  "multipart/form-data": {
    "files": {
      "model": "<test.h5>"
    }
  }
}

Response samples

Content type
application/json
{
  • "modelId": "222-333-444",
  • "modelName": "mnist.h5"
}

Get all existing models

Returns all previously uploaded models.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "models": {
    }
}

Delete all existing models

Deletes all existing models for the current user

Notes: This operation cannot be reverted.

Authorizations:
bearerAuth

Responses

Get a model's files

Returns the specified model's files

Authorizations:
bearerAuth
path Parameters
modelId
required
string

The model's identifier

Responses

Response samples

Content type
application/octet-stream
filedata

Check that the given model is valid for the evaluation engine

Returns a json with an "ok" or "ko" value, indicating wether the model is supported or not by the evaluation engine.

If the status is "ko", a list of error is provided.

Authorizations:
bearerAuth
path Parameters
modelId
required
string

The model's identifier

Responses

Response samples

Content type
application/json
{
  • "file_version": "0.1",
  • "status": "ok",
  • "errors": [ ]
}

Get a model's metadata

Returns the specified model's metadata

Authorizations:
bearerAuth
path Parameters
modelId
required
string

The model's identifier

Responses

Response samples

Content type
application/json
{
  • "id": "e091d492-be02-11eb-965e-65d067e2ea43",
  • "creationDate": "26/05/2021-11:15:13",
  • "originalFileName": "Sign_language_Digits.h5",
  • "fileName": "e091d492-be02-11eb-965e-65d067e2ea43.h5",
  • "format": "keras",
  • "modelFingerprint": "a709666cd8efe575967d6fdf18b18e22",
  • "modelSize": 4577456,
  • "source": null,
  • "labels": null,
  • "inputShape": [
    ],
  • "evaluations": [ ]
}

Delete an existing model

Deletes the specified model and its data files

Note: The route itself allows the suppression of models that are being used by evaluations. This may render them inexploitable. The frontend application emits an alert and offers to delete the associated evaluations but not the API.

Authorizations:
bearerAuth
path Parameters
modelId
required
string

The model's identifier

Responses

Response samples

Content type
application/json
{
  • "message": "Error: too many files found with name : fashion_mnist_duplicate.h5",
  • "locations": [
    ],
  • "matching_ids": [
    ]
}

Utils

Utility endpoints

User authentication

Allows user authentication with login and password.

Notes:

  • This route should be the first one called when starting a user session.
  • Takes login/password as parameters.
  • Returns a token used to check the user credentials, allowing them to access its workspace ressources (input, model, evaluations)...
Authorizations:
bearerAuth
Request Body schema: application/json
login
required
string

The login used for authentication

password
required
string

The password used for authentication

Responses

Request samples

Content type
application/json
{
  • "login": "saimplev2",
  • "password": "saimplev2"
}

Response samples

Content type
application/json
{
  • "access_token": "XXX",
  • "expires_in": 36000,
  • "not-before-policy": 1635352754,
  • "refresh_expires_in": 1800,
  • "refresh_token": "YYY",
  • "scope": "email profile",
  • "session_state": "064a6909-7d25-4cdd-bb8e-1cb027ca4e42",
  • "token_type": "Bearer"
}

Get API Status

Gets API Status

Notes: This route is mostly used by application to ensure the availability of the backend.

Authorizations:
bearerAuth

Responses

Get supported layers

Gets the list of supported layers in the evaluation engine and their supported onnx versions.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "file_version": "0.2",
  • "Description": "0.2",
  • "Activation_functions": [
    ],
  • "binary_operators": [
    ],
  • "form_operators": [
    ],
  • "layers": [
    ]
}

Get versions of the different Saimple entities

Gets the versions of the different Saimple entities.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "api": {
    },
  • "fae": {
    },
  • "fae-libAD": {
    },
  • "abstari": {
    }
}

Get license informations of the different Saimple entities

Gets the license informations of the different Saimple entities.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "check_msg": "",
  • "expiration_date": "",
  • "hostid": "",
  • "license_path": "",
  • "license_check": "DISABLED",
  • "product": "",
  • "product_version": "",
  • "start": "",
  • "client": "",
  • "is_valid": true
}