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

@@ -77,8 +77,9 @@ paths:
           in: query
           required: false
           description: |
-            Start and end index (exclusive) within query results of
-            entities shown on page, separated by an 'L'
+            Start index within query results of the first entity and
+            total number of entities to be shown on one page,
+            separated by an 'L'
           schema:
             type: string
             example: 0L10
@@ -93,7 +94,18 @@ paths:
               example:
                 UserInfo:
                   Roles:
-                    - administration
+                    - anonymous
+                Query:
+                  string: "FIND RECORD"
+                  results: 82
+                  cached: true
+                  etag: "some-etag-hash"
+                entity:
+                  - name: "Result 1"
+                    id: 101
+                  - name: "Result 2"
+                    id: 102
+                  
 components:
   schemas:
     Response:
@@ -310,4 +322,5 @@ components:
           type: string
           xml:
             attribute: true
+        # TODO: Add remaining query properties. Also add POV Filter?