Web Services Definition » History » Revision 38
Revision 37 (Kurt Gerber, 09 Jan 2020 20:47) → Revision 38/40 (Kurt Gerber, 09 Jan 2020 20:52)
h1. API / Web Services Requirements
h2. Request services
The existing API is documented here: https://qcat.readthedocs.io/en/latest/api/docs.html
h3. 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"] @
h2. Requirements for services to add / update cases
The following new webservice endpoints must be developed.
h3. 1. Authentification endpoint
* See the following page for further specifications: [[API Authentification ]]
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.
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":https://qcat.readthedocs.io/en/latest/api/v2.html#structure-of-configuration
*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:*
<pre><code class="json">
{"success":"true",
"code": "technologies_4534"
}
</code></pre>
h3. 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:
<pre><code class="json">
{
"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"
}
</code></pre>
The value of the key "uid" is what is then really stored in the 'image' key field of the corresponding questionnaire.
h3. 4. Endpoint to edit a case
*Endpoint:* @/api/v2/en/questionnaires/{configuration}/{edition}/{identifier}/@
* *This endpoint exits already*
* Downloading %{background:#F2D5A0} downloading last version of a single case case, for which the respective user is authorised to see%
*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 latest version of a case
*POST:*
For an adapted locking mechanism see [[/wiki/API_Authentification_#Case-locking-mechanism]]
*POST data:* a valid, updated questionnaire based on the corresponding "configuration template":https://qcat.readthedocs.io/en/latest/api/v2.html#structure-of-configuration
*Response:*
<pre><code class="json">
{"success":"true",
"code": "technologies_4534"
}
</code></pre>
h3. 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