WOCAT » QCAT

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

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":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}/edit/{identifier}@

%{background:#F2D5A0} Opening a case in draft mode to edit has to take care of different things:% 

* %{background:#F2D5A0}Only the newest version of a case can be edited% 

* %{background:#F2D5A0}Only if  the case is public or in draft mode%

*Open question:* %{background:#F2D5A0}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":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