From 36d918021767f8925db5c3ca67e9ba7aa6e02748 Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Mon, 8 Nov 2021 11:21:43 +0100
Subject: [PATCH] REL: Prepare CHANGELOG, update API versions from v1alpha1 to
v1
---
CHANGELOG.md | 42 ++++++++++++++++---
proto/caosdb/CMakeLists.txt | 4 +-
.../caosdb/entity/{v1alpha1 => v1}/main.proto | 6 +--
proto/caosdb/info/{v1alpha1 => v1}/main.proto | 6 +--
4 files changed, 44 insertions(+), 14 deletions(-)
rename proto/caosdb/entity/{v1alpha1 => v1}/main.proto (99%)
rename proto/caosdb/info/{v1alpha1 => v1}/main.proto (91%)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 10652f1..dfc9976 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,16 +5,46 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-## [Unreleased]
+## [0.1] 2021-11-08
+(Timm Fitschen)
+
+The initial release contains two separate GRPC APIs, one for transactions of
+entities (Entity API) and one for general information about the server.
+
+Note that the authentication of clients (and/or servers) is not defined as
+a protobuf API. Instead, the server should provide authentication schemes based
+on the transport protocols (usually HTTP/2) and indicate the options in its own
+documentation.
### Added
-### Changed
+#### Entity API (v1)
+
+The Entity API defines entities, the first-class citizens of CaosDB and the
+transactions for insertion, updates, retrieval and deletion of entities and the
+upload and download of binary files.
+
+Entities can be retrieved by id or by query. Several entities can be processed
+a single transaction and the transaction types (insertion, update, deletion,
+retrieval) can be mixed in a single transaction.
+
+Notable current limitations of the API:
+
+ * The error handling is still not perfect. Properties cannot have messages
+ right now and only a few error messages are defined in the API.
+ * The version message can only represent the version id of an entity. The
+ History cannot be retrieved.
+ * The entity's access control lists cannot be changed or retrieved.
+ * The entity state cannot be changed or retrieved.
+ * A lot of flags (e.g. inheritance among other things) which are implemented
+ in the REST-API of CaosDB are not supported.
-### Deprecated
+The current release is designed in a way that these limitation can be be
+overcome in future releases of the API without braking backwards compatibility.
-### Removed
+#### Info API (v1)
-### Fixed
+The Info API is strict read-only API which provides useful non-confidential
+information about the server.
-### Security
+The initial release of this API is quite limited. Only the
diff --git a/proto/caosdb/CMakeLists.txt b/proto/caosdb/CMakeLists.txt
index 1ecce67..870d96e 100644
--- a/proto/caosdb/CMakeLists.txt
+++ b/proto/caosdb/CMakeLists.txt
@@ -19,8 +19,8 @@
#
set(CAOSDB_API_PACKAGES
- caosdb.info.v1alpha1
- caosdb.entity.v1alpha1
+ caosdb.info.v1
+ caosdb.entity.v1
)
# pass variable to parent scope
diff --git a/proto/caosdb/entity/v1alpha1/main.proto b/proto/caosdb/entity/v1/main.proto
similarity index 99%
rename from proto/caosdb/entity/v1alpha1/main.proto
rename to proto/caosdb/entity/v1/main.proto
index 605711e..78bd4d4 100644
--- a/proto/caosdb/entity/v1alpha1/main.proto
+++ b/proto/caosdb/entity/v1/main.proto
@@ -18,12 +18,12 @@
// along with this program. If not, see <https://www.gnu.org/licenses/>.
//
-// This is the main file of the caosdb.entity.v1alpha1 package.
+// This is the main file of the caosdb.entity.v1 package.
syntax = "proto3";
option java_multiple_files = true;
-option java_package = "org.caosdb.api.entity.v1alpha1";
+option java_package = "org.caosdb.api.entity.v1";
option cc_enable_arenas = true;
-package caosdb.entity.v1alpha1;
+package caosdb.entity.v1;
// Data type for references to other entities.
message ReferenceDataType {
diff --git a/proto/caosdb/info/v1alpha1/main.proto b/proto/caosdb/info/v1/main.proto
similarity index 91%
rename from proto/caosdb/info/v1alpha1/main.proto
rename to proto/caosdb/info/v1/main.proto
index d1291da..9af2d93 100644
--- a/proto/caosdb/info/v1alpha1/main.proto
+++ b/proto/caosdb/info/v1/main.proto
@@ -18,12 +18,12 @@
// along with this program. If not, see <https://www.gnu.org/licenses/>.
//
-// This is the main file of the caosdb.info.v1alpha1 package.
+// This is the main file of the caosdb.info.v1 package.
syntax = "proto3";
option java_multiple_files = true;
-option java_package = "org.caosdb.api.info.v1alpha1";
+option java_package = "org.caosdb.api.info.v1";
-package caosdb.info.v1alpha1;
+package caosdb.info.v1;
// The version of an agent (following SemVer 2.0.0)
message VersionInfo {
--
GitLab