diff --git a/.gitignore b/.gitignore
index 6ebd032b84c79dfa2a4bbf4df81cadce8a2a1555..2b4a625324a2696c6ff9d8ecf55254451d57ef9c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,8 @@ build/
bin/
target/
_apidoc/
+src/doc/development/api/xml/out/
+src/doc/_static/api/
# But include server-side scripting
!/scripting/bin
@@ -39,3 +41,6 @@ authtoken/
# python
__pycache__
*~
+
+# Documentation binaries
+src/doc/development/api/xml/*.jar
diff --git a/.gitlab/merge_request_templates/Default.md b/.gitlab/merge_request_templates/Default.md
index a8c5b719ad5f8e18c2fd68d2daa1e5c62f94d450..ac68afc814247e5a64395315e630d5de44a5f306 100644
--- a/.gitlab/merge_request_templates/Default.md
+++ b/.gitlab/merge_request_templates/Default.md
@@ -40,7 +40,7 @@ guidelines](https://gitlab.com/caosdb/caosdb/-/blob/dev/REVIEW_GUIDELINES.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?
+- [ ] Check: Are there specifications? Are they satisfied?
For further good practices have a look at [our review guidelines](https://gitlab.com/caosdb/caosdb/-/blob/dev/REVIEW_GUIDELINES.md).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d6ed1a5a986a3dc64c79dcb4b6abc168ba27494..9269fd416dfedb5e532a0fc53cbf3549f145eecc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+* An openAPI specification of the XML api
+
### Changed
### Deprecated
@@ -17,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
-- #145 Documentation of importances and inheritance
+* #145 Documentation of importances and inheritance
* Missing sources of the easy-unit dependency.
### Security
diff --git a/src/doc/Makefile b/src/doc/Makefile
index 4f177fd3850423c3005829a75a2b37625dc68a87..1f0af46e75a27dc9ff8d124782fca27400e4a240 100644
--- a/src/doc/Makefile
+++ b/src/doc/Makefile
@@ -1,4 +1,3 @@
-# ** header v3.0
# This file is a part of the CaosDB Project.
#
# Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
@@ -16,8 +15,7 @@
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
-#
-# ** end header
+
# This Makefile is a wrapper for sphinx scripts.
#
@@ -28,10 +26,15 @@
SPHINXOPTS ?= -a
SPHINXBUILD ?= sphinx-build
SPHINXAPIDOC ?= javasphinx-apidoc
+
+APIXMLDIR = development/api/xml/
SOURCEDIR = .
BUILDDIR = ../../build/doc
-.PHONY: doc-help Makefile apidoc
+# Don't make the documentation of the XML api at least until
+# https://github.com/OpenAPITools/openapi-generator/issues/9923 is
+# resolved
+.PHONY: doc-help Makefile apidoc # apixml
# Put it first so that "make" without argument is like "make help".
doc-help:
@@ -39,9 +42,12 @@ doc-help:
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile apidoc
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+%: Makefile apidoc # apixml
+ $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# sphinx-build -M html . ../../build/doc
apidoc:
- @$(SPHINXAPIDOC) -o _apidoc --update --title="CaosDB Server" ../main/
+ $(SPHINXAPIDOC) -o _apidoc --update --title="CaosDB Server" ../main/
+
+apixml:
+ $(MAKE) -C $(APIXMLDIR) doc
diff --git a/src/doc/development/api/xml/Makefile b/src/doc/development/api/xml/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..b2314adb191575895a89770332261b505543e0f3
--- /dev/null
+++ b/src/doc/development/api/xml/Makefile
@@ -0,0 +1,35 @@
+# This file is a part of the CaosDB Project.
+#
+# Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
+# Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+# Build to sphinx' static dir
+BUILDDIR ?= ../../../_static/api/xml/
+
+
+.PHONY: doc
+doc:
+ mkdir -p $(BUILDDIR)
+ [ -e openapi-generator-cli.jar ] || wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.2.0/openapi-generator-cli-5.2.0.jar -O openapi-generator-cli.jar
+ java -jar openapi-generator-cli.jar generate -i caosdb_openapi.yaml --config openapi_config.json -g html2 -o $(BUILDDIR)
+
+
+
+## Not needed (the same code anyway?)
+
+# [ -e swagger-codegen-cli.jar ] || wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.27/swagger-codegen-cli-3.0.27.jar -O swagger-codegen-cli.jar
+# java -jar swagger-codegen-cli.jar generate -i caosdb_openapi.yaml -l html2 -o $(BUILDDIR)
diff --git a/src/doc/development/api/xml/caosdb_openapi.yaml b/src/doc/development/api/xml/caosdb_openapi.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..b2e0b7449d0ab9c4bc147692862aa69107828bac
--- /dev/null
+++ b/src/doc/development/api/xml/caosdb_openapi.yaml
@@ -0,0 +1,482 @@
+openapi: "3.0.3"
+info:
+ title: CaosDB XML REST API
+ description: The XML API of CaosDB, see also https://docs.indiscale.com/caosdb-server
+ version: 0.0-poc.1
+servers:
+ - url: https://demo.indiscale.com
+ description: Demo server, will reset its content from time to time.
+paths:
+ /Entity/{id}:
+ get:
+ operationId: getEntity
+ summary: Return an Entity with a given integer id.
+ description: This is the most direct way to return a single Entity.
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: The internal integer id of the entity to be retrieved.
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: The entity
+ 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: 146
+ name: "John Lennon's guitar"
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ Parent:
+ - name: Guitar
+ id: 110
+ Version:
+ id: "some-version-string"
+ head: true
+ Predecessor:
+ id: "some-old-version-string"
+ Property:
+ - name: electric
+ id: 106
+ datatype: "BOOLEAN"
+ value: "TRUE"
+ importance: FIX
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ delete:
+ operationId: deleteEntity
+ summary: Delete the entity with the given id
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: integer id of the entity to be deleted
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: The entity that was deleted
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+
+ /Entity/:
+ get:
+ operationId: executeQuery
+ summary: Return the entities matching the given query
+ description: Use arbitrary CaosDB queries to retrieve all matching entities
+ parameters:
+ - name: query
+ in: query
+ required: true
+ description: The actual query that is to be executed
+ schema:
+ type: string
+ - name: P
+ in: query
+ required: false
+ description: |
+ 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
+ pattern: "[0-9]+L[0-9]+"
+ responses:
+ '200':
+ description: "The query result"
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Response"
+ example:
+ UserInfo:
+ Roles:
+ - anonymous
+ Query:
+ string: "FIND RECORD"
+ results: 82
+ cached: true
+ etag: "some-etag-hash"
+ entity:
+ - name: "Result 1"
+ 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
+ put:
+ operationId: updateEntity
+ summary: Update one or more entities
+ description: Attach one or several entities to be updated on the server
+ requestBody:
+ required: true
+ description: The entity or the entities to be updated
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Request"
+ example:
+ entity:
+ - name: "MyNewRecord"
+ id: 365
+ description: "Test"
+ Parent:
+ - name: "ParentType"
+ id: 123
+ Property:
+ - name: "SomeProperty"
+ id: 124
+ datatype: "INTEGER"
+ value: 3
+ - name: "SomeOtherProperty"
+ id: 125
+ datatype: "String"
+ value: "Hello"
+ responses:
+ '200':
+ description: The updated 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: 12346
+ baseuri: "https://demo.indiscale.com"
+ count: 1
+ UserInfo:
+ username: admin
+ realm: PAM
+ roles:
+ - administration
+ entity:
+ id: 365
+ name: "MyNewRecord"
+ description: "Test"
+ Version:
+ id: "some-new-version-string"
+ head: true
+ Predecessor:
+ id: "some-version-string"
+ Permissions:
+ - name: "RETRIEVE:ENTITY"
+ - name: "RETRIEVE:ACL"
+ Parent:
+ - name: "ParentType"
+ id: 123
+ Property:
+ - name: "SomeProperty"
+ id: 124
+ datatype: "INTEGER"
+ value: 3
+ - name: "SomeOtherProperty"
+ id: 125
+ datatype: "String"
+ value: "Hello"
+components:
+ schemas:
+ Response:
+ type: object
+ description: Server response containing metadata and the requested entity
+ properties:
+ UserInfo:
+ $ref: "#/components/schemas/UserInfo"
+ username:
+ $ref: "#/components/schemas/username"
+ realm:
+ $ref: "#/components/schemas/realm"
+ srid:
+ $ref: "#/components/schemas/srid"
+ timestamp:
+ $ref: "#/components/schemas/timestamp"
+ baseuri:
+ type: string
+ description: URI to which the request was sent
+ xml:
+ attribute: true
+ count:
+ type: integer
+ description: Number of entities contained in this response
+ xml:
+ attribute: true
+ entity:
+ type: array
+ items:
+ $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:
+ id:
+ $ref: "#/components/schemas/id"
+ name:
+ $ref: "#/components/schemas/name"
+ description:
+ type: string
+ example: This is a measurement.
+ xml:
+ attribute: true
+ Permissions:
+ type: array
+ items:
+ $ref: "#/components/schemas/Permission"
+ xml:
+ wrapped: true
+ Property:
+ type: array
+ items:
+ $ref: "#/components/schemas/Property"
+ Parent:
+ type: array
+ items:
+ $ref: "#/components/schemas/Parent"
+ Version:
+ $ref: "#/components/schemas/Version"
+ xml:
+ name: 'xml-entity'
+ UserInfo:
+ type: object
+ description: Information about the user that submitted the request
+ properties:
+ Roles:
+ type: array
+ items:
+ $ref: "#/components/schemas/Role"
+ xml:
+ wrapped: true
+ username:
+ $ref: "#/components/schemas/username"
+ realm:
+ $ref: "#/components/schemas/realm"
+ Role:
+ type: object
+ properties:
+ text:
+ type: string
+ example: "anonymous"
+ xml:
+ name: Role
+ username:
+ type: string
+ example: admin
+ xml:
+ attribute: true
+ realm:
+ type: string
+ example: PAM
+ xml:
+ attribute: true
+ srid:
+ type: string
+ xml:
+ attribute: true
+ timestamp:
+ type: integer
+ xml:
+ attribute: true
+ id:
+ description: The integer id of this entity
+ type: integer
+ xml:
+ attribute: true
+ example: 3
+ name:
+ type: string
+ example: Measurement
+ xml:
+ attribute: true
+ Permission:
+ type: object
+ properties:
+ name:
+ type: string
+ example: "RETRIEVE:ENTITY"
+ xml:
+ attribute: true
+ xml:
+ name: Permission
+ importance:
+ type: string
+ description: Importance of this property
+ xml:
+ attribute: true
+
+ Property:
+ type: object
+ required:
+ - id
+ - datatype
+ - importance
+ properties:
+ datatype:
+ type: string
+ description: The CaosDB datatype of this property
+ example: BOOLEAN
+ xml:
+ attribute: true
+ id:
+ $ref: "#/components/schemas/id"
+ name:
+ $ref: "#/components/schemas/name"
+ importance:
+ $ref: "#/components/schemas/importance"
+ Value:
+ type: array
+ items:
+ type: string
+ unit:
+ type: string
+ xml:
+ attribute: true
+ Permissions:
+ type: array
+ items:
+ $ref: "#/components/schemas/Permission"
+ xml:
+ wrapped: true
+
+ Parent:
+ type: object
+ properties:
+ id:
+ $ref: "#/components/schemas/id"
+ name:
+ $ref: "#/components/schemas/name"
+
+ Version:
+ type: object
+ properties:
+ id:
+ type: string
+ xml:
+ attribute: true
+ head:
+ type: boolean
+ xml:
+ attribute: true
+ Predecessor:
+ type: object
+ properties:
+ id:
+ type: string
+ xml:
+ attribute: true
+ Successor:
+ type: object
+ properties:
+ id:
+ type: string
+ xml:
+ attribute: true
+
+ Query:
+ type: object
+ properties:
+ string:
+ type: string
+ xml:
+ attribute: true
+ results:
+ type: integer
+ xml:
+ attribute: true
+ cached:
+ type: boolean
+ xml:
+ attribute: true
+ etag:
+ type: string
+ xml:
+ attribute: true
+ # TODO: Add remaining query properties. Also add POV Filter?
+
diff --git a/src/doc/development/api/xml/openapi_config.json b/src/doc/development/api/xml/openapi_config.json
new file mode 100644
index 0000000000000000000000000000000000000000..f27abea7e89a96ba0b39aa0f1ee5f3fdc836c854
--- /dev/null
+++ b/src/doc/development/api/xml/openapi_config.json
@@ -0,0 +1,8 @@
+{
+ "appName": "CaosDB",
+ "appDescription": "CaosDB, the open data management toolkit",
+ "infoUrl": "https://docs.indiscale.com/caosdb-server",
+ "infoEmail": "info@indiscale.com",
+ "licenseInfo": "License: AGPLv3",
+ "licenseUrl": "https://gitlab.com/caosdb/caosdb-server/-/blob/dev/LICENSE.md"
+}
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 2ae00f7e685407325903159257d6561912f94a66..21fd891c083e7932d8b342d93992b2d02158364e 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -19,8 +19,10 @@ Welcome to caosdb-server's documentation!
Welcome to the CaosDB, the flexible semantic data management toolkit!
-This documentation helps you to :doc:`get started<README_SETUP>`, explains the most important
-:doc:`concepts<concepts>` and has information if you want to :doc:`develop<development/devel>` CaosDB yourself.
+This documentation helps you to :doc:`get started<README_SETUP>`,
+explains the most important :doc:`concepts<concepts>` and has
+information if you want to :doc:`develop<development/devel>` CaosDB
+yourself.
Indices and tables
diff --git a/src/doc/specification/Specification-of-the-Entity-API.md b/src/doc/specification/Entity_Overview.md
similarity index 95%
rename from src/doc/specification/Specification-of-the-Entity-API.md
rename to src/doc/specification/Entity_Overview.md
index 5ef05b7898d40e43f320c9e3519a6d9520efffcd..ca197e50050d9ba2c593973148627c4d56708a67 100644
--- a/src/doc/specification/Specification-of-the-Entity-API.md
+++ b/src/doc/specification/Entity_Overview.md
@@ -1,6 +1,6 @@
-# Specification of the Entity API
+# Overview of the CaosDB Entities' structure
-**Warning:** This specification is outdated. It is included to serve as a starting point for a more up-to-date description of the entity API.
+**Warning:** This overview may be outdated.
Version: 0.1.0r1
diff --git a/src/doc/specification/entity_api.rst b/src/doc/specification/entity_api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3f6bdbcf700aaeebbe7d49fe79ac47c4ad4303ad
--- /dev/null
+++ b/src/doc/specification/entity_api.rst
@@ -0,0 +1,24 @@
+The Entity API
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+ :hidden:
+
+ Overview of the CaosDB Entities' structure<Entity_Overview>
+
+.. note::
+
+ Until the corresponding `bug of openapi-codegen <https://github.com/OpenAPITools/openapi-generator/issues/9923>`_
+ is resolved, the documentation of the OpenAPI specification of the
+ entity API is best rendered by gitlab.
+
+The details of the specification, including interactive examples, can
+be found `here
+<https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/tree/dev/src/doc/development/api/xml/caosdb_openapi.yaml>`_.
+Note that some commands may require authentication, which can be done with
+an authentication cookie as described in the :doc:`api
+documentation<Authentication>`. Specialities of the :doc:`scripting
+api<Server-side-scripting>` and the :doc:`file api<Fileserver>` are
+explained in the corresponding sections of the specifications.
diff --git a/src/doc/specification/index.rst b/src/doc/specification/index.rst
index 3609aa4a8eb6165adf6070faae26bfb8bd4ba50f..69677277fc793d513aa21f506295567340d462e1 100644
--- a/src/doc/specification/index.rst
+++ b/src/doc/specification/index.rst
@@ -1,20 +1,18 @@
-
Specification
=============
-
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
- :hidden:
-
- AbstractProperty
- Fileserver
- Record
- Specification of the Entity API <Specification-of-the-Entity-API>
- Authentication
- Datatype
- Paging
- RecordType
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+ :hidden:
+
+ AbstractProperty
+ Fileserver
+ Record
+ Authentication
+ Datatype
+ Paging
+ RecordType
Server side scripting <Server-side-scripting>
Specification of the Message API <Specification-of-the-Message-API>
-
+ Specification of the Entity API <entity_api>