DOC: Document the XML API

Summary

See https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/238 and https://gitlab.indiscale.com/caosdb/customers/lfpb/management/-/issues/407. Introduce a minimal documentation of the specifications of the XML API using openAPI.

Focus

The formulation of the API is in src/doc/development/api/xml/caosdb_openapi.yaml. Some text and a new section for the entity API have been added to the Specifications section, but since openapi-codegen fails to produce reasonable output, we leave it to gitlab to render the specification and just link to the file blob.

Test Environment

make doc and have a look at the section in Specification.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related Issues
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/doc/development/api/xml/caosdb_openapi.yaml

@@ -105,7 +105,66 @@ paths:
                     id: 101
                   - name: "Result 2"
                     id: 102
-                  
+    post:
+      operationId: insertEntity
+      summary: Insert one or more entities
+      description: Upload one or several entities to be inserted on the server
+      requestBody:
+        required: true
+        description: The entity or the entities to be inserted
+        content:
+          application/xml:
+            schema:
+              $ref: "#/components/schemas/Request"
+            example:
+              entity:
+                - name: "MyNewRecord"
+                  description: "Test"
+                  Parent:
+                    - name: "ParentType"
+                      id: 123
+                  Property:
+                    - name: "SomeProperty"
+                      id: 124
+                      datatype: "INTEGER"
+                      value: 3
+      responses:
+        '200':
+          description: The inserted entity object(s) with information added by the server
+          content:
+            application/xml:
+              schema:
+                $ref: "#/components/schemas/Response"
+              example:
+                username: admin
+                realm: PAM
+                srid: "some-srid"
+                timestamp: 12345
+                baseuri: "https://demo.indiscale.com"
+                count: 1
+                UserInfo:
+                  username: admin
+                  realm: PAM
+                  roles:
+                    - administration
+                entity:
+                  id: 365
+                  name: "MyNewRecord"
+                  description: "Test"
+                  Version:
+                    id: "some-version-string"
+                    head: true
+                  Permissions:
+                    - name: "RETRIEVE:ENTITY"
+                    - name: "RETRIEVE:ACL"
+                  Parent:
+                    - name: "ParentType"
+                      id: 123
+                  Property:
+                    - name: "SomeProperty"
+                      id: 124
+                      datatype: "INTEGER"
+                      value: 3                
 components:
   schemas:
     Response:
@@ -138,6 +197,14 @@ components:
             $ref: "#/components/schemas/entity"
         Query:
           $ref: "#/components/schemas/Query"
+    Request:
+      type: object
+      description: Request to be inserted or updated
+      properties:
+        entity:
+          type: array
+          items:
+            $ref: "#/components/schemas/entity"
     entity:
       type: object
       properties: