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.

Endpoint: /api/v2/configuration/technologies/

Allowed method: GET

Request Header:

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

Response: List of editions for given configuration, e.g.

• {"editions": ["2018", "2006"]

2. Without the specific configuration endpoint (like 'technologies'), the response should be an array of available configurations.

Endpoint: /api/v2/configuration/

Allowed method: GET

Request Header:

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

Response: List of configurations, e.g.

• {"configurations": ["technologies", "approaches", "unccd"]

Requirements for services to add / update cases¶

The following new webservice endpoints must be developed.

1. Authentification endpoint¶

This needs a new technical concept. Goals:

• Existing authentication must still work (without need to refresh the token), but only for "non-app" requests
• Requests from the "app" must periodically refresh the authentication
• For all requests from the app, the header "User-Agent: app" (or something similar) must be set.

Current idea: provide a new authentication backend; skip existing authentication for requests from the app based on some POST flag.
Question/Idea: What about JSON Web Token (JWT)?
h3. 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