Web Services Definition » History » Revision 25
Revision 24 (Kurt Gerber, 13 Dec 2018 16:54) → Revision 25/40 (Kurt Gerber, 14 Dec 2018 10:08)
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 response 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. h2. Requirements for services to add / update cases The following new webservice endpoints must be developed. h3.1. Authentification endpoint To upload a case, a user has to authenticate himself. Therefore an authentification endpoint is needed. %{background:#F2D5A0} 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 'sessionid'. This sessionid 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:* <pre><code class="json"> {"sessionid":"09249249243729342123ad232dc"} </code></pre> 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@ * @sessionid: <session_id>@ 6xn26rwsy0r0k2yn5bsoq2qiyssg9mrs@ * @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@ * @sessionid: <session_id>@ * @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@ * @sessionid: <session_id>@ * @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 case: