Use Problem JSON (RFC 7807) to report errors in REST API. Fixes #27

annif/rest.py

@@ -1,6 +1,7 @@
 """Definitions for REST API operations. These are wired via Connexion to
 methods defined in the Swagger specification."""
 
+import connexion
 import annif.project
 from annif.hit import HitFilter
 
@@ -14,16 +15,21 @@ def show_project(project_id):
     try:
         project = annif.project.get_project(project_id)
     except ValueError:
-        return "Project '{}' not found".format(project_id), 404
-
+        return connexion.problem(
+            status=404,
+            title='Project not found',
+            detail="Project '{}' not found".format(project_id))
     return project.dump()
 
 
 def analyze(project_id, text, limit, threshold):
     try:
         project = annif.project.get_project(project_id)
     except ValueError:
-        return "Project '{}' not found".format(project_id), 404
+        return connexion.problem(
+            status=404,
+            title='Project not found',
+            detail="Project '{}' not found".format(project_id))
 
     hit_filter = HitFilter(limit, threshold)
     hits = hit_filter(project.analyze(text))

swagger/annif.yaml

@@ -5,10 +5,6 @@ info:
 schemes:
   - http
 basePath: /v1
-consumes:
-  - application/json
-produces:
-  - application/json
 parameters:
   project_id:
     name: project_id
@@ -35,6 +31,9 @@ paths:
     get:
       summary: show project information
       operationId: annif.rest.show_project
+      produces:
+        - application/json
+        - application/problem+json
       parameters:
         - $ref: '#/parameters/project_id'
       responses:
@@ -43,7 +42,9 @@ paths:
           schema:
             $ref: '#/definitions/Project'
         '404':
-          description: project not found
+          description: Project not found
+          schema:
+            $ref: '#/definitions/Problem'
       tags:
         - Project administration
   '/projects/{project_id}/analyze':
@@ -54,6 +55,7 @@ paths:
         - application/x-www-form-urlencoded
       produces:
         - application/json
+        - application/problem+json
       parameters:
         - $ref: '#/parameters/project_id'
         - name: text
@@ -144,3 +146,43 @@ definitions:
         type: array
         items:
           $ref: '#/definitions/AnalysisResult'
+  Problem:
+    type: object
+    properties:
+      type:
+        type: string
+        format: uri
+        description: |
+          An absolute URI that identifies the problem type.  When dereferenced,
+          it SHOULD provide human-readable documentation for the problem type
+          (e.g., using HTML).
+        default: 'about:blank'
+        example: 'https://zalando.github.io/problem/constraint-violation'
+      title:
+        type: string
+        description: |
+          A short, summary of the problem type. Written in english and readable
+          for engineers (usually not suited for non technical stakeholders and
+          not localized); example: Service Unavailable
+      status:
+        type: integer
+        format: int32
+        description: |
+          The HTTP status code generated by the origin server for this occurrence
+          of the problem.
+        minimum: 100
+        maximum: 600
+        exclusiveMaximum: true
+        example: 503
+      detail:
+        type: string
+        description: |
+          A human readable explanation specific to this occurrence of the
+          problem.
+        example: Connection to database timed out
+      instance:
+        type: string
+        format: uri
+        description: |
+          An absolute URI that identifies the specific occurrence of the problem.
+          It may or may not yield further information if dereferenced.