API / Web Services Requirements¶

Request services¶

The existing API is documented here: https://qcat.readthedocs.io/en/latest/api/docs.html

Required missing request services:¶

• There is an endpoint to get the configuration for a specific questionnaire and edition: https://https://qcat.wocat.net/en/api/v2/configuration/technologies/2018/

1. Whithout the 'edition' endpoint, it should respond with an array of available editions. Now it answers with a 'Not found' html page.

2. Without the specific configuration endpoint (like 'technologies'), the response should be an array of available configurations. Now it answers with a 'Not found' html page.

Requirements for services to add / update cases¶

The following new webservice endpoints must be developed.

1. Authentification endpoint¶

To upload a case, a user has to authenticate himself. Therefore an authentification endpoint is needed.

The existing authorization token serves only as authorization to access the API.
The token is application based and always the same for a certain application, independently of the user working with the application.

• The user has to authenticate before any data is uploaded or non-public downloaded.
• After a successfull authentification, the server sends a token. This token has to be added to the request header for any subsequent POST request. Should work a bit as on the web UI with the sessionid in the cookie.
• Limitations on client side? (to discuss)

Endpoint: /api/v2/user-token/

Allowed method: POST

Post data:

• username: The username of a WOCAT account
• password: The password of the corresponding WOCAT account

Response:

{"usertoken":"09249249243729342123ad232dc"}

2. Endpoint to create new case¶

Endpoint: /api/v2/en/questionnaires/<configuration>/<edition>/create

Allowed method: POST

POST data: a valid questionnaire based on the corresponding configuration template

Request Header:

• Authorization: Token AUTH_TOKEN
• usertoken: <usertoken>
• Accept: application/json or Accept: application/xml
• Content-Type: application/json or Content-Type: application/xml

Response:

{"success":"true",
 "code": "technologies_4534" 
}

3. image/file upload¶

This should be handled the same as already done the ui version.

Adding an image uploads it directly with POST to https://qcat.wocat.net/en/upload

As response it gets a JSON like this:

{
    "success": true,
    "uid": "cfb23a06-385a-47c5-8a94-83cae1fd90b7",
    "interchange": [
        "[/upload/9d/a/9da8b521-7130-48df-ba31-549016a748e5.jpg, (default)]",
        "[/upload/0a/3/0a3fea13-1485-4ec8-92ee-351eef561d2d.jpg, (small)]",
        "[/upload/17/0/170251f9-a9ea-4945-a714-0beaebb7c750.jpg, (medium)]",
        "[/upload/cf/b/cfb23a06-385a-47c5-8a94-83cae1fd90b7.jpg, (large)]" 
    ],
    "url": "/upload/cf/b/cfb23a06-385a-47c5-8a94-83cae1fd90b7.jpg" 
}

The value of the key "uid" is what is then really stored in the 'image' key field of the corresponding questionnaire.

4. Endpoint to edit a case¶

Endpoint: /api/v2/en/questionnaires/{configuration}/{edition}/edit/{identifier}

Opening a case in draft mode to edit has to take care of different things:

• Only the newest version of a case can be edited
• Only if the case is public or in draft mode

Open question: Locking mechanism in the environment of apps going offline has to be discussed

Request header:

• Authorization: Token AUTH_TOKEN
• usertoken: <usertoken>
• Accept: application/json or Accept: application/xml
• Content-Type: application/json or Content-Type: application/xml

Allowed method: GET, POST

GET:

• Response would be the case in 'draft mode'

POST:

POST data: a valid, updated questionnaire based on the corresponding configuration template

Response:

{"success":"true",
 "code": "technologies_4534" 
}

5. Endpoint to get mydata¶

Endpoint: /api/v2/en/questionnaires/mydata

Allowed method: GET

Request Header:

• Authorization: Token AUTH_TOKEN
• usertoken: <usertoken>
• Accept: application/json or Accept: application/xml
• Content-Type: application/json or Content-Type: application/xml

Response: List of public or draft cases of which the user is the compiler