Merge branch 'issue25' into 'master'

#25 Recherche/Definition Endpoints

See merge request !50

learning/team1/Rest Api best practices/readme.md

+# Recherche best practice Rest-API (URI, Parameter, Rueckgabewerte, Fehlerbehandlung)
+
+1. **URI**: <br/>
+    in URI: <br/>
+	- sollte man **Nomen** als Ressource verwenden <br/> Beispiel: /users, /orders
+	- sollte man **keine Verben** verwenden <br/> Beispiel: /getUsers, /getOrders
+	- sollten **collections in Plural** sein <br/> Beispiel: /articles
+<br/><br/>**CRUD Operations**: <br/>
+Man kann folgende Operationen auf eine Ressource machen: <br/>
+**create (POST)** : um eine neue Ressource zu erstellen <br/>
+**Read (GET)** : um eine Ressource abzurufen <br/>
+**Update (PUT oder PATCH)** : um eine Ressource zu ersetzen (PUT) oder zu bearbeiten (PATCH) <br/>
+**Delete (DELETE)** : um eine Ressource zu löschen 
+2. **Parameter**: <br/>
+Parameter sind dafür da, um Daten zu suchen, zu filtern und zu sortieren. <br/>
+	- man sollte mit **query parameter** arbeiten, wenn man eine **kleine Collection** betrachtet <br/>
+	Beispiel: Ich möchte Details über Arbeiter aus kamerun haben<br/> http://localhost:8080/Employees?country=cameroon <br/>
+	- man sollte mit uri parameter arbeiten, wenn man eine große Collection betrachtet<br/> Beispiel: Ich möchte alle Details von der Abteilung 1, 2, 3 haben <br/>http://localhost:8080/Departments/123 <br/>
+3. **Rückgabewerte**: sollten in Json Format sein. 
+4. **Fehlerbehandlung**: 
+	Die Fehler müssen behandelt werden und entsprechenden Standardfehlercode zurückgeben: <br/># clientseitige Fehler: 
+	**400**: Bad Request → für clientseitige Eingabe fehlgeschlagen <br/>
+	**401**: Unauthorized →, wenn der Benutzer nicht authentifiziert ist und versucht eine Ressource 
+	zuzugreifen <br/>
+	**403**: Forbidden →, wenn der Benutzer authentifiziert ist und kein Recht hat eine Ressource 
+	zuzugreifen <br/>
+	**404**: Not Found: wenn eine Ressource nicht gefunden wird <br/>
+	**500**: Internal server error: Standard serverseitig Fehlermeldung. wenn etwas serverseitig schiefgeht <br/>
+	**502**: Bad Gateway →, wenn eine Response vom Server invalid ist <br/>
+	**503**: Service Unavailable →, wenn etwas Unerwartetes auf der Serverseite passiert <br/>
+
+
+## Quelle:
+* https://www.merixstudio.com/blog/best-practices-rest-api-development/ <br/>
+* https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/ <br/>
+* https://blog.dreamfactory.com/best-practices-for-naming-rest-api-endpoints/ <br/>
+* https://swagger.io/resources/articles/best-practices-in-api-design/ <br/>
+
+# Recherche andere ähnliche APIs, z.B. https://rapidapi.com/darkmanaminovic/api/question-generator inkl. Dokumentation
+
+* https://opentdb.com/api_config.php <br/>
+* https://jservice.io/ <br/>  
+* https://quizapi.io/ <br/> 
+* **Ergebnisse**: festgelegte Anzahl von Fragen nach kathegorien mit Antwortmöglichkeiten generieren <br/>
+
+# Swagger-Doku
+
+OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. <br/>
+Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs <br/>
+
+* Quelle: https://swagger.io/docs/specification/about/ <br/>
+* Dokumentation: https://swagger.io/specification/ <br/>
+
+
+
+

src/ktor-server/src/main/kotlin/de/h_da/fbi/smebt/intentfinder/server/Application.kt

@@ -3,12 +3,13 @@ package de.h_da.fbi.smebt.intentfinder.server
 import de.h_da.fbi.smebt.intentfinder.server.nlp.PythonBridge
 import io.ktor.application.*
 import io.ktor.features.*
-
+import io.ktor.http.*
 import io.ktor.response.*
 import io.ktor.routing.*
 import io.ktor.serialization.*
 import kotlinx.serialization.json.Json
 import registerUploadRoutes
+import java.lang.RuntimeException
 
 
 fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)
@@ -20,6 +21,16 @@ fun Application.module() {
         })
     }
 
+    install(StatusPages){
+
+        exception<InternalServerErrorException> { cause ->
+            call.respond(HttpStatusCode.InternalServerError)
+            throw cause
+        }
+
+        statusFile(HttpStatusCode.NotFound, filePattern = "error/error#.html")
+    }
+
     routing {
         get("/summary") {
             val response = PythonBridge().getSummary("test bridge")
@@ -28,6 +39,51 @@ fun Application.module() {
         get("/") {
             call.respondText("IntentFinder is available")
         }
+
+        // Definition eines Endpunkts zum Hochladen einer DOCX-Datei
+        post("/file/{chatbotId}") {
+            call.respondText("file was successful uploaded")
+        }
+
+        // Definition endpoint zur Änderung eine bereits existierende docx
+        put("/file/{chatbotId}/{id}/{filename}"){
+
+        }
+
+        // Definition eines Endpunkts zur Definition einer FAQ-Webseite mit JSON-Konfiguration
+        post("/faqRessource/{chatbotId}/{jsonStructure}"){
+
+        }
+
+        // get faq with Json Configuration
+        get("/faqRessource"){
+            //Rückgabe  Json Object (vgl. #38)
+        }
+
+        // Definition eines Endpunkts zur Definition einer Docx-Datei mit JSON-Konfiguration
+        post("/docxRessource/{chatbotId}/{filename}"){
+
+        }
+
+        // get docx file with Json Configuration
+        get("/docxRessource"){
+            //Rückgabe  Json Object (vgl. #37)
+        }
+
+        // Definition endpoint zum Auslesen aller hochgeladener docx mit status
+        get("/files"){
+
+        }
+
+        // Routen ohne Funktionalität
+        routing{
+
+        }
+
     }
     registerUploadRoutes()
 }
+
+class InternalServerErrorException : RuntimeException()
+
+

src/ktor-server/src/main/resources/error/error404.html

+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <title>The Page cannot be found!</title>
+    </head>
+    <body>
+        <h1>Not Found!</h1>
+    </body>
+</html>
\ No newline at end of file

swagger/swagger.yaml

+openapi: "3.0.0"
+info:
+  title: "Intent Finder"
+  version: "1.0"
+  description: "Api that allows users to test Endpoint from Intent Finder"
+  termsOfService: "https://code.fbi.h-da.de/pse-trapp-public/intentfinder"
+  contact:
+    name: "Djilo"
+    email: "djilocyrille@gmail.com"
+  license:
+    name: "IngenieurDuKuat Licence"
+    url: "https://ingenieurdukuatt.fr"
+servers:
+  - url: localhost:8080
+    description: "server for the Api"
+paths:
+  /summary:
+    get:
+      description: "get a list of summary"
+      responses:
+        '200':
+          description: "OK"
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  summary:
+                    type: string
+                  value:
+                    type: string
+        '405':
+          description: "Invalid input"
+  /:
+    get:
+      description: "get the root of endpoint"
+      responses:
+        '200':
+          description: "OK"
+          content:
+            application/json:
+              schema:
+                type: string
+
+  /file:
+    post:
+      description: "Uploade a docx document in the Server"
+      parameters:
+        - name: "file"
+          in: query
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  type: string
+                filname:
+                  type: string
+                id:
+                  type: integer
+      responses:
+        200:
+          description: "OK"
+        500:
+          description: "internal server error"
+
+  /files:
+    get:
+      description: "get All docx file"
+      responses:
+        '200':
+          description: "OK"
+          content:
+            application/json:
+              schema:
+                type: string
+        '500':
+          description: "Internal server error"
+        '404':
+          description: "not found"
\ No newline at end of file