inital

LICENSE.md

@@ -0,0 +1,15 @@
+# License
+Copyright (C) 2016-2021 CI HUB GmbH
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU 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 General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.

README.md

@@ -0,0 +1,45 @@
+[![Software License](https://img.shields.io/badge/license-GPLv3-brightgreen.svg?style=flat-square)](LICENSE.md)
+[![Latest Stable Version](https://img.shields.io/packagist/v/w/simple-rest-adapter-bundle.svg?style=flat-square)](https://packagist.org/packages/ci-hub/simple-rest-adapter-bundle)
+
+This bundle adds a simple read-only REST API endpoint to [Pimcore DataHub](https://github.com/pimcore/data-hub)
+for Assets and DataObjects. All exposed data can be configured, is indexed in Elasticsearch and delivered from there
+for better query performance and scalability.
+
+Therefore, it can be used to connect Pimcore to other systems or to connect Front-End applications.
+
+## Features in a nutshell
+* Configure a schema and expose data like with other DataHub adapters via Drag & Drop.
+* All data gets indexed in Elasticsearch indices and delivered from there (no additional load on the database
+  when accessing data via REST endpoints).
+* Endpoint documentation and test via Swagger UI.
+* Available endpoints:
+  * **tree-items**: Method to load all elements of a tree level with additional support for:
+    * paging
+    * filtering
+    * fulltext search
+    * ordering
+    * aggregations – provide possible values for fields to create filters
+  * **search**: Method to search for elements, returns elements of all types (no folder structures)
+    with additional support for:
+    * paging
+    * filtering
+    * fulltext search
+    * ordering
+    * aggregations – provide possible values for fields to create filters
+  * **get-element**: Method to get one single element by type and ID.
+* Endpoint security via bearer token that has to be sent as header with every request.
+
+![Schema Configuration](docs/images/schema.png "Schema Configuration")
+![Swagger UI](docs/images/swagger_ui.png "Swagger UI")
+
+## Further Information
+* [Installation & Bundle Configuration](docs/00-installation-configuration.md)
+* [Endpoint Configuration Details](docs/01-endpoint-configuration.md)
+* [Indexing Details](docs/02-indexing.md)
+
+## License
+**CI HUB GmbH**, Benkertstrasse 4, 14467 Potsdam, Germany  
+[www.ci-hub.com](https://ci-hub.com), [email protected]  
+Copyright © 2021 CI HUB GmbH. All rights reserved.
+
+For licensing details please visit [LICENSE.md](LICENSE.md)

composer.json

@@ -0,0 +1,44 @@
+{
+  "name": "ci-hub/simple-rest-adapter-bundle",
+  "type": "pimcore-bundle",
+  "license": "GPL-3.0-or-later",
+  "description": "Simple REST Adapter for Pimcore DataHub",
+  "keywords": [
+    "pimcore",
+    "pimcore-bundle"
+  ],
+  "homepage": "https://github.com/ci-hub-gmbh/SimpleRESTAdapterBundle",
+  "authors": [
+    {
+      "name": "CI HUB GmbH",
+      "email": "[email protected]",
+      "homepage": "https://www.ci-hub.com"
+    }
+  ],
+  "require": {
+    "php": ">=7.2",
+    "ongr/elasticsearch-dsl": "^7.0",
+    "pimcore/data-hub": "~1.0.11",
+    "pimcore/pimcore": "^6.9",
+    "symfony/messenger": "^4.0",
+    "zircote/swagger-php": "^3.0"
+  },
+  "require-dev": {
+    "phpstan/phpstan": "^0.12",
+    "phpstan/phpstan-symfony": "^0.12",
+    "roave/security-advisories": "dev-master",
+    "symplify/easy-coding-standard": "^9.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "CIHub\\Bundle\\SimpleRESTAdapterBundle\\": "src/SimpleRESTAdapterBundle/"
+    }
+  },
+  "extra": {
+    "pimcore": {
+      "bundles": [
+        "CIHub\\Bundle\\SimpleRESTAdapterBundle\\SimpleRESTAdapterBundle"
+      ]
+    }
+  }
+}

docs/00-installation-configuration.md

@@ -0,0 +1,80 @@
+# Installation
+This bundle depends on the [Pimcore DataHub](https://github.com/pimcore/data-hub), which needs to be installed first.
+
+To install the Simple REST Adapter complete following steps:
+* Install via composer
+  ```
+  composer require ci-hub/simple-rest-adapter-bundle:^1.0
+  ```
+* Enable via command-line (or inside the Pimcore extension manager)
+  ```
+  bin/console pimcore:bundle:enable SimpleRESTAdapterBundle
+  ```
+* Clear cache and reload Pimcore
+  ```
+  bin/console cache:clear --no-warmup
+  ```
+
+> Make sure, that the priority of the Pimcore DataHub is higher than the priority of the Simple REST Adapter.
+> This can be specified as parameter of the `pimcore:bundle:enable` command or in the Pimcore extension manager.
+
+## Bundle Configuration
+Configure Elasticsearch hosts and index name prefix with Symfony configuration:
+
+```yaml
+# Default configuration for "SimpleRESTAdapterBundle"
+simple_rest_adapter:
+
+    # Prefix for index names.
+    index_name_prefix:    datahub_restindex
+
+    # List of Elasticsearch hosts.
+    es_hosts:
+
+        # Default:
+        - localhost
+
+    # Global Elasticsearch index settings.
+    index_settings:
+
+        # Defaults:
+        number_of_shards:    5
+        number_of_replicas:  0
+        max_ngram_diff:      20
+        analysis:
+            analyzer:
+                datahub_ngram_analyzer:
+                    type:                custom
+                    tokenizer:           datahub_ngram_tokenizer
+                    filter:
+                        - lowercase
+                datahub_whitespace_analyzer:
+                    type:                custom
+                    tokenizer:           datahub_whitespace_tokenizer
+                    filter:
+                        - lowercase
+            normalizer:
+                lowercase:
+                    type:                custom
+                    filter:
+                        - lowercase
+            tokenizer:
+                datahub_ngram_tokenizer:
+                    type:                nGram
+                    min_gram:            2
+                    max_gram:            20
+                    token_chars:
+                        - letter
+                        - digit
+                datahub_whitespace_tokenizer:
+                    type:                whitespace
+```
+
+> Supported Elasticsearch version: ^7.0
+
+To make sure the indexing queue is processed and index is filled, following command has to be executed on
+a regular basis, e.g. every 5 minutes.
+
+```
+*/5 * * * * php /var/www/html/bin/console messenger:consume datahub_es_index_queue --limit=20 --time-limit=240 >/dev/null 2>&1
+```

docs/01-endpoint-configuration.md

@@ -0,0 +1,37 @@
+# Endpoint Configuration Details
+Every DataHub configuration creates a separate endpoint with its own settings and its own data.
+Following configuration options are possible for each endpoint.
+
+### General
+See type and name of configuration and define description and if the endpoint is active or not.
+
+![General settings](images/general.png "General settings")
+
+### Schema Definition
+Define available data entities and their schema (= available fields) for the endpoint. Also define if Assets should
+be considered in tree items and search requests and if originals and/or what thumbnails should be used for delivery.
+
+![Schema settings](images/schema.png "Schema settings")
+
+### Workspaces
+Define workspaces for Assets and DataObjects and so manage what data should be actually exposed via the endpoint.
+It is possible to include and explicitly exclude folders.
+
+![Workspace settings](images/workspaces.png "Workspace settings")
+
+### Label Settings
+Define nice looking labels for different languages for each field. Each request includes the labels for used fields in
+response in an additional data structure. They then can be used by the client application.
+
+Additionally define what fields will be considered for aggregation calculation for facet navigation.
+
+![Label settings](images/label_settings.png "Label settings")
+
+> Please consider that the field list is build based on indexed data. So saving the configuration and processing
+> index queue might be necessary to see up-to-date list here.
+
+### Delivery Settings
+Define (or generate) an API key for securing the endpoint.
+This API key needs to be sent as security header with every request.
+
+![Delivery settings](images/delivery_settings.png "Delivery settings")

docs/02-indexing.md

@@ -0,0 +1,20 @@
+# Indexing Details
+All data that is delivered by simple REST endpoints is indexed in Elasticsearch indices.
+Queries and data delivery takes place directly out of Elasticsearch (not from the Pimcore database).
+
+For each DataHub configuration separate Elasticsearch indices will be created and updated.
+
+**Indexing of data** takes places asynchronously with a Symfony Messenger queue, and the consume queue command
+`messenger:consume datahub_es_index_queue`. This command needs to be executed on a regular basis, e.g. every 5 minutes.
+
+**Index mapping and queue filling** takes place automatically when creating and updating DataHub configurations.
+
+Multiple indices are created per endpoint – one for each DataObject class, one for DataObject folders, one for Assets
+and one for Asset folders.
+
+**Tree Hierarchy Management**: The indexing process tries to keep a valid folder structure in an index.
+Based on workspace settings a combined parent folder is calculated. This combined parent folder,
+might be a sub folder of the parent folder in Pimcore folder structure, and all element paths are rewritten to it.
+
+Also, it might be possible, that due to workspace and data schema settings, missing links in folder structure occur.
+In this case, the indexing process creates virtual folders to fill up these gaps.