From e3630dcd08573ed5a7f1b853d6cced31bb77a8af Mon Sep 17 00:00:00 2001
From: Stefan Haun <tux@netz39.de>
Date: Sun, 23 Aug 2020 22:38:16 +0200
Subject: [PATCH] Add endpoints for entities to OAS3

---
 OAS3.yml | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)

diff --git a/OAS3.yml b/OAS3.yml
index b676911..16c65a6 100644
--- a/OAS3.yml
+++ b/OAS3.yml
@@ -44,6 +44,161 @@ paths:
         '500':
           $ref: '#/components/responses/InternalError'
 
+  /entities:
+    parameters:
+      - in: header
+        name: Authentication
+        schema:
+          type: string
+        description: Authentication token
+    post:
+      summary: Create an entity
+      tags:
+        - entities
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Entity JSON
+      responses:
+        '201':
+          description: Entity has been created
+          content:
+            text/plain:
+              schema:
+                type: string
+                description: Entity ID (5 digit hex)
+                example: 1b3d5
+        '400':
+          $ref: '#/components/responses/InvalidInput'
+        '401':
+          $ref: '#/components/responses/AuthenticationRequired'
+        '403':
+          $ref: '#/components/responses/NotAllowed'
+    get:
+      summary: Retrieve all entities (can be limited to a specific time and active members)
+      tags:
+        - entities
+      parameters:
+        - in: query
+          name: time
+          schema:
+            type: string
+            format: date-time
+            description: Use database projection at given time
+        - in: query
+          name: fieldset
+          schema:
+            type: string
+            enum: [summary, sepa, all]
+          description: Select the set of fields returned for each entity
+        - in: query
+          name: activeMembersOnly
+          schema:
+            type: boolean
+          description: Return only active members (w/r/t the provided timestamp)
+      responses:
+        '200':
+          description: Request successfully processed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  time:
+                    type: string
+                    format: date-time
+                  fieldset:
+                    type: string
+                    enum: [summary, sepa, all]
+                  activeMembersOnly:
+                    type: boolean
+                  entities:
+                    type: array
+                    items:
+                      type: string
+                      example: entities JSON
+        '400':
+          $ref: '#/components/responses/InvalidInput'
+        '401':
+          $ref: '#/components/responses/AuthenticationRequired'
+        '403':
+          $ref: '#/components/responses/NotAllowed'
+
+  /entities/{id}:
+    parameters:
+      - in: path
+        name: id
+        required: true
+        schema:
+          type: string
+        description: Entity ID
+      - in: header
+        name: Authentication
+        schema:
+          type: string
+        description: Authentication token
+    post:
+      summary: Update an existing entity
+      tags:
+        - entities
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Entity JSON
+      responses:
+        '200':
+          description: Update was successful
+        '400':
+          $ref: '#/components/responses/InvalidInput'
+        '401':
+          $ref: '#/components/responses/AuthenticationRequired'
+        '403':
+          $ref: '#/components/responses/NotAllowed'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    get:
+      summary: Retrieve a specific entity (can be limited to a specific time and active members)
+      tags:
+        - entities
+      parameters:
+        - in: query
+          name: time
+          schema:
+            type: string
+            format: date-time
+            description: Use database projection at given time
+        - in: query
+          name: fieldset
+          schema:
+            type: string
+            enum: [summary, sepa, all]
+          description: Select the set of fields returned for each entity
+        - in: query
+          name: activeMembersOnly
+          schema:
+            type: boolean
+          description: Return only active members (w/r/t the provided timestamp)
+      responses:
+        '200':
+          description: Entity has been found
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Entity JSON
+                example: entities JSON
+        '400':
+          $ref: '#/components/responses/InvalidInput'
+        '401':
+          $ref: '#/components/responses/AuthenticationRequired'
+        '403':
+          $ref: '#/components/responses/NotAllowed'
+        '404':
+          $ref: '#/components/responses/NotFound'
 
 components:
   schemas:
@@ -72,6 +227,8 @@ components:
           schema:
             type: string
             example: error message
+    NotFound:
+      description: The specified object could not be found (404)
     InternalError:
       description: Internal error during execution (500)
       content:
-- 
2.45.2