Define REST API learn method. Implementation still missing conversion…

… of input

annif/rest.py

@@ -64,3 +64,21 @@ def analyze(project_id, text, limit, threshold):
         return server_error(err)
     hits = hit_filter(result)
     return {'results': [hit._asdict() for hit in hits]}
+
+
+def learn(project_id, documents):
+    """learn from documents and return an empty 204 response if succesful"""
+
+    try:
+        project = annif.project.get_project(
+            project_id, min_access=Access.hidden)
+    except ValueError:
+        return project_not_found_error(project_id)
+
+#   TODO should convert the documents to a corpus object
+#    try:
+#        project.learn(documents)
+#    except AnnifException as err:
+#        return server_error(err)
+
+    return None, 204

annif/swagger/annif.yaml

@@ -90,6 +90,38 @@ paths:
             $ref: '#/definitions/Problem'
       tags:
         - Automatic subject indexing
+  '/projects/{project_id}/learn':
+    post:
+      summary: learn from manually indexed documents
+      operationId: annif.rest.learn
+      consumes:
+        - application/json
+      produces:
+        - application/json
+        - application/problem+json
+      parameters:
+        - $ref: '#/parameters/project_id'
+        - name: documents
+          in: body
+          description: documents to learn from
+          required: true
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/IndexedDocument'
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: Project not found
+          schema:
+            $ref: '#/definitions/Problem'
+        '503':
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/Problem'
+      tags:
+        - Learning from feedback
 definitions:
   ProjectBackend:
     description: A backend of a project
@@ -133,7 +165,7 @@ definitions:
         example: 'http://example.org/subject1'
       label:
         type: string
-        example: 'Archaeology'
+        example: Archaeology
       score:
         type: number
         example: 0.85
@@ -148,6 +180,23 @@ definitions:
         type: array
         items:
           $ref: '#/definitions/AnalysisResult'
+  IndexedDocument:
+    description: A document with attached, known good subjects
+    properties:
+      text:
+        type: string
+        example: "A quick brown fox jumped over the lazy dog."
+      subjects:
+        type: array
+        items:
+          type: object
+          properties:
+            uri:
+              type: string
+              example: 'http://example.org/subject1'
+            label:
+              type: string
+              example: 'Vulpes vulpes'
   Problem:
     type: object
     properties:
@@ -169,8 +218,10 @@ definitions:
       status:
         type: integer
         format: int32
-        description: |
-          The HTTP status code generated by the origin server for this occurrence
+        description: >
+          The HTTP status code generated by the origin server for this
+          occurrence
+
           of the problem.
         minimum: 100
         maximum: 600
@@ -185,6 +236,8 @@ definitions:
       instance:
         type: string
         format: uri
-        description: |
-          An absolute URI that identifies the specific occurrence of the problem.
+        description: >
+          An absolute URI that identifies the specific occurrence of the
+          problem.
+
           It may or may not yield further information if dereferenced.