d.vinci ATS Test Provider REST API documentation version 1.3

https://{customer}.dvinci.de/restApi/

General usage

The d.vinci ATS Test Provider REST API uses JSON as content type for requests and responses with charset UTF-8.

CAUTION: The Test Provider API endpoint has to be implemented by the test provider itself! This documentation only provides information expected by the d.vinci system from the API endpoint.

Authentication by "Dvinci_Header"

For authentication it is required to pass custom HTTP-Headers for every request.

Dvinci-API-User: myApiUser
Dvinci-API-Token: bjOa8wvQyZWtCYYFB3xlPeC79S7xjsCgb2ZZZ92n

An API user can be created by any user who can login to the intern web-ui of d.vinci ATS https://{customer}.dvinci.de/intern and has the permission to create API users.

Curl-Example

curl -i -H "Accept: application/json" -H "Dvinci-API-User: myApiUser" -H "Dvinci-API-Token: bjOa8wvQyZWtCYYFB3xlPeC79S7xjsCgb2ZZZ92n" https://{customer}.dvinci.de/restApi/testResults/{identifier} { status: "PENDING" }

HTTP Response Codes

200: OK: Everything was fine
401: Unauthorized: Not existing User or not an api user or wrong token
403: Forbidden: Valid api user, without permission to access this api method or requested entity or entity/id not exists
404: Requested resource not available
405: Method not allowed
422: Unable to process request: A JSON-Object with field "errorMsg" is returned

Securing "External Links" with JWT

Some endpoints (e.g. test results) allow to add links to external systems. These links can be secured by JWT. For additional information, please go to https://jwt.io/.

The URLs that should be enhanced by JWT can be specified by a d.vinci ATS administrator. The generated token will be added as a query parameter named "jwt".

URL-Example

https://external-link-to-your-system.com?your=param&jwt=eyJhbGciOiJIUzI1NiJ9.eyJkdmluY2lVc2VyIjoicmVzdC1hcGktdG8tZHZpbmNpLXVzZXIiLCJkdmluY2lVc2VySWQiOjEzMzcsImF1ZCI6Imh0dHA6Ly93d3cuZHZpbmNpLmRlIiwiaXNzIjoibG9jYWwiLCJpYXQiOjE0ODA1MDE2OTU5ODl9.NEEje-nzcpEJJPRv_kvRrblcZ1y6GN-tWZ6tJDv1QwY

Additionally it is possible to position the JWT with a given external link if placeholder (jwt) is used, see Test results.

Changes

From version 1.2 to 1.3

All APIs with externalLinks were modified:
- It is possible to position the JWT with a given external link if placeholder (jwt) is used, see Test results.

From version 1.1 to 1.2

Introduced new test-result-status "TEST_COMPLETED"

From version 1.0 to 1.1

Added functionality to add external links to test results

Initial release 1.0

Test result API endpoint

Test Provider API endpoint

/testProviderApiEndpoint/ post

post

The d.vinci system requires a test provider API endpoint (testProviderApiEndpoint). This API endpoint information must be configured by a d.vinci user and may contain optional HTTP header parameters, e.g. for authentication. A POST request will be sent to this endpoint from the d.vinci system to request a test from a test provider.

Request
Response

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "gender": {
            "enum": ["male", "female", "null"]
        },
        "salutation": {
            "type": [
                "string",
                "null"
            ]
        },
        "title": {
            "type": [
                "string",
                "null"
            ]
        },
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "email": {
            "type": [
                "string",
                "null"
            ]
        },
        "language": {
            "description": "ISO2 formatted language, e.g.: de",
            "type": "string"
        },
        "resultUrl": {
            "description": "A unique URL to d.vinci system for the particular test. This URL is used by test providers to make PUT calls to d.vinci to update test data.",
            "type": "string"
        }
    },
    "required": [
        "firstName",
        "lastName",
        "language",
        "resultUrl"
    ]
}

Example:

{
    "gender": "male",
    "salutation": "Herr",
    "title": null,
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "max.mustermann@dvinci.de",
    "language": "de",
    "resultUrl": "https://demo022.dvinci.de/restApi/testResults/1d3nt1f13r"
}

HTTP status code 200

This response is expected by d.vinci when no error occurs

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "url": {
            "type": "string"
        },
        "username": {
            "type": [
                "string",
                "null"
            ]
        },
        "password": {
            "type": [
                "string",
                "null"
            ]
        },
        "expireDate": {
            "description": "Latest date to complete the test. Can be 'null' or ISO8601 date-time format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).",
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        }
    },
    "required": [
        "url"
    ]
}

Example:

{
    "url": "https://api.testanbieter.de/startTest/234512345",
    "username": "test-username",
    "password": "test-password",
    "expireDate": "2016-01-01T15:00:00.000+01:00"
}

HTTP status code 400

Every status except status 200 will be processed as error

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "error": {
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Example:

{
    "error": "Test provider error message, that will be displayed for users."
}

Test results

/testResults/{id} put

put

Update a test result

Secured by Dvinci_Header

Request
Response

URI Parameters

id: required (string)
id of the requested test

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "status": {
            "enum": ["PENDING", "TEST_PASSED", "TEST_FAILED", "TEST_COMPLETED", "PROCESS_FAILED"]
        },
        "testDate": {
            "description": "Date when a test was completed. Can be 'null' or ISO8601 date-time format (yyyy-MM-dd'T'HH:mm:ss.SSSZZ).",
            "type": [
                "string",
                "null"
            ],
            "format": "date-time"
        },
        "result": {
            "description": "Total result of a test",
            "type": [
                "string",
                "null"
            ]
        },
        "furtherResults": {
            "description": "A detail list of test result.",
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "label": {
                        "description": "Some description.",
                        "type": "string"
                    },
                    "result": {
                        "description": "Corresponding result to the label",
                        "type": "string"
                    }
                }
            }
        },
        "externalLinks": {
            "description": "List of links to access additional information offered by test provider.",
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "label": {
                        "description": "Label for the link",
                        "type": "string"
                    },
                    "url": {
                        "description": "External URL. Can contain the placeholder (jwt) that will be replaced if the URL is accessed.",
                        "type": "string"
                    },
                    "faIcon": {
                        "description": "A Font Awesome icon of version 5.x that is displayed in regular (with class 'far'). Has to start with 'fa-'.",
                        "type": "string"
                    }
                }
            }
        }
    },
    "required": [
        "status"
    ]
}

Example:

{
    "status": "TEST_PASSED",
    "testDate": "2016-01-01T00:00:00.000+01:00",
    "result": "30%",
    "furtherResults": [
        {
            "label": "Task A",
            "result": "20%"
        },
        {
            "label": "Task B",
            "result": "40%"
        },
        {
            "label": "Task C",
            "result": "10%"
        }
    ],
    "externalLinks": [
        {
            "label": "Link A",
            "url": "http://url-to-some-file.de",
            "faIcon": "fa-file-pdf-o"
        },
        {
            "label": "Link B",
            "url": "http://url-to-some-other-file.de",
            "faIcon": "fa-calendar-o"
        },
        {
            "label": "Link C",
            "url": "http://url-to-some-page/(jwt)/content",
            "faIcon": "fa-external-link-square-alt"
        }
    ]
}

HTTP status code 200

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "sucess": {
            "type": "boolean"
        }
    },
    "required": [
        "sucess"
    ]
}

Example:

{ "success": true }

HTTP status code 403

Lacking permission to access this api method or requested entity or the entity/id does not exists

HTTP status code 422

This error is caused by validation errors of the given data.

mandatory: The property is mandatory
typeMismatch: The given value does not match the required format
url.invalid: The given URL is not valid

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "fieldErrors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "allowed": {
                        "type": "string"
                    },
                    "notAllowed": {
                        "type": "string"
                    },
                    "field": {
                        "type": "string"
                    },
                    "code": {
                        "type": "string"
                    }
                },
                "required": [
                    "field",
                    "code"
                ]
            }
        },
        "errorMsg": {
            "type": "string"
        }
    },
    "required": [
        "errorMsg"
    ]
}

Example:

{
    "fieldErrors": [
        {
            "field": "status",
            "code": "mandatory"
        },
        {
            "field": "testDate",
            "code": "typeMismatch"
        }
    ],
    "errorMsg": "Entity not valid"
}

d.vinci ATS Test Provider REST API documentation version 1.3

Test Provider API endpoint

post /testProviderApiEndpoint/

Body

HTTP status code 200

Body

HTTP status code 400

Body

Test results

put /testResults/{id}

URI Parameters

Body

HTTP status code 200

Body

HTTP status code 403

HTTP status code 422

Body