Skip to content
Snippets Groups Projects
Commit ef757d02 authored by Daniel Hornung's avatar Daniel Hornung
Browse files

Merge branch 'f-doc-xml' into 'dev' 

DOC: Document the XML API

See merge request !24
parents 215ff1a5 8cdb1949
No related branches found
No related tags found
2 merge requests!41REL: update changelog, bump version of pom.xml, update DEPENDENCIES,!24DOC: Document the XML API
Pipeline #11534 passed
Stage: setup
Stage: test
Stage: deploy
Hide whitespace changes
Inline Side-by-side
Showing
with 591 additions and 29 deletions
.gitignore
+ 5
− 0
View file @ ef757d02
......@@ -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
.gitlab/merge_request_templates/Default.md
+ 1
− 1
View file @ ef757d02
......@@ -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).
......
CHANGELOG.md
+ 3
− 1
View file @ ef757d02
......@@ -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
......
src/doc/Makefile
+ 13
− 7
View file @ ef757d02
# ** 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
src/doc/development/api/xml/Makefile 0 → 100644
+ 35
− 0
View file @ ef757d02
# 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)
src/doc/development/api/xml/caosdb_openapi.yaml 0 → 100644
+ 482
− 0
View file @ ef757d02
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?
src/doc/development/api/xml/openapi_config.json 0 → 100644
+ 8
− 0
View file @ ef757d02
{
"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"
}
src/doc/index.rst
+ 4
− 2
View file @ ef757d02
......@@ -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
......
src/doc/specification/Specification-of-the-Entity-API.md → src/doc/specification/Entity_Overview.md
+ 2
− 2
View file @ ef757d02
# 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
......
src/doc/specification/entity_api.rst 0 → 100644
+ 24
− 0
View file @ ef757d02
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.
src/doc/specification/index.rst
+ 14
− 16
View file @ ef757d02
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>
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment