[#58520] add an endpoint to fetch the hierarchy

app/models/queries/custom_fields/hierarchy/item_query.rb

@@ -0,0 +1,42 @@
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# 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 2
+# 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, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+module Queries
+  module CustomFields
+    module Hierarchy
+      class ItemQuery
+        include ::Queries::BaseQuery
+        include ::Queries::UnpersistedQuery
+
+        def self.model
+          CustomField::Hierarchy::Item
+        end
+      end
+    end
+  end
+end

app/services/custom_fields/hierarchy/hierarchical_item_service.rb

@@ -112,11 +112,23 @@ def reorder_item(item:, new_sort_order:)
         Success()
       end
 
-      def soft_delete_item(item)
+      def soft_delete_item(item:)
         # Soft delete the item and children
         raise NotImplementedError
       end
 
+      def hashed_subtree(item:, depth:)
+        if depth >= 0
+          Success(item.hash_tree(limit_depth: depth + 1))
+        else
+          Success(item.hash_tree)
+        end
+      end
+
+      def descendant_of?(item:, parent:)
+        item.descendant_of?(parent) ? Success() : Failure()
+      end
+
       private
 
       def create_root_item(custom_field)

config/locales/en.yml

@@ -295,12 +295,19 @@ en:
 
   dry_validation:
     errors:
+      integer?: "must be an integer"
+      filled?: "must be filled"
+      greater_or_equal_zero: "must be greater or equal to 0"
+      not_found: "not found"
       rules:
         label:
-          filled?: "must be filled"
           not_unique: "must be unique within the same hierarchy level"
+        parent:
+          not_descendant: "must be a descendant of the hierarchy root"
     rules:
       label: "Label"
+      parent: "Parent"
+      depth: "Depth"
 
   global_search:
     placeholder: "Search in %{app_title}"
@@ -1591,7 +1598,7 @@ en:
   create_new_page: "Wiki page"
 
   date:
-    abbr_day_names: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
+    abbr_day_names: [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
     abbr_month_names:
       [
         ~,

docs/api/apiv3/components/examples/hierarchy_item_collection_filtered_response.yml

@@ -0,0 +1,62 @@
+description: |-
+  Filtered response of a hierarchy structure starting at a specific parent and restricting the depth.
+value:
+  _type: Collection
+  total: 3
+  count: 3
+  _embedded:
+    elements:
+      - _type: HierarchyItem
+        id: 1338
+        label: Stormtroopers
+        short: ST
+        depth: 1
+        _links:
+          self:
+            href: /api/v3/custom_field_items/1338
+            name: Stormtroopers
+          parent:
+            href: /api/v3/custom_field_items/1337
+            name: null
+          children:
+            - href: /api/v3/custom_field_items/1340
+              name: ST-377
+            - href: /api/v3/custom_field_items/1341
+              name: ST-422
+      - _type: HierarchyItem
+        id: 1340
+        label: ST-377
+        short: null
+        depth: 2
+        _links:
+          self:
+            href: /api/v3/custom_field_items/1340
+            name: ST-377
+          parent:
+            href: /api/v3/custom_field_items/1338
+            name: Stormtroopers
+          children:
+            - href: /api/v3/custom_field_items/1480
+              name: ST-377-200
+            - href: /api/v3/custom_field_items/1481
+              name: ST-377-201
+      - _type: HierarchyItem
+        id: 1341
+        label: ST-422
+        short: null
+        depth: 2
+        _links:
+          self:
+            href: /api/v3/custom_field_items/1341
+            name: ST-422
+          parent:
+            href: /api/v3/custom_field_items/1338
+            name: Stormtroopers
+          children:
+            - href: /api/v3/custom_field_items/1580
+              name: ST-422-137
+            - href: /api/v3/custom_field_items/1581
+              name: ST-422-138
+  _links:
+    self:
+      href: /api/v3/custom_field/42/items?parent=1338&depth=1

docs/api/apiv3/components/examples/hierarchy_item_collection_response.yml

@@ -0,0 +1,51 @@
+description: |-
+  Simple response of a hierarchy structure starting at root.
+value:
+  _type: Collection
+  total: 37
+  count: 37
+  _embedded:
+    elements:
+      - _type: HierarchyItem
+        id: 1337
+        label: null
+        short: null
+        depth: 0
+        _links:
+          self:
+            href: /api/v3/custom_field_items/1337
+            name: null
+          parent:
+            href: null
+          children:
+            - href: /api/v3/custom_field_items/1338
+              name: Stormtroopers
+            - href: /api/v3/custom_field_items/1339
+              name: Dark Troopers
+      - _type: HierarchyItem
+        id: 1338
+        label: Stormtroopers
+        short: ST
+        depth: 1
+        _links:
+          self:
+            href: /api/v3/custom_field_items/1338
+            name: Stormtroopers
+          parent:
+            href: /api/v3/custom_field_items/1337
+            name: null
+          children:
+            - href: /api/v3/custom_field_items/1340
+              name: ST-377
+            - href: /api/v3/custom_field_items/1341
+              name: ST-422
+      - _type: HierarchyItem
+        _hint: hierarchy item shortened for brevity
+        id: 1340
+        label: ST-377
+        short: null
+        depth: 2
+      - _hint: hierarchy item shortened for brevity
+  _links:
+    self:
+      href: /api/v3/custom_field/42/items

docs/api/apiv3/components/examples/hierarchy_item_response.yml

@@ -0,0 +1,20 @@
+description: |-
+  Simple response of a single item of a custom field of type hierarchy.
+value:
+  _type: HierarchyItem
+  id: 1338
+  label: Stormtroopers
+  short: ST
+  depth: 1
+  _links:
+    self:
+      href: /api/v3/custom_field_items/1338
+      name: Stormtroopers
+    parent:
+      href: /api/v3/custom_field_items/1337
+      name: null
+    children:
+      - href: /api/v3/custom_field_items/1340
+        name: ST-377
+      - href: /api/v3/custom_field_items/1341
+        name: ST-422

docs/api/apiv3/components/schemas/hierarchy_item_collection_model.yml

@@ -0,0 +1,30 @@
+# Schema: HierarchyItemCollectionModel
+---
+allOf:
+  - $ref: './collection_model.yml'
+  - type: object
+    required:
+      - _links
+      - _embedded
+    properties:
+      _links:
+        type: object
+        required:
+          - self
+        properties:
+          self:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  This hierarchy item collection
+
+                  **Resource**: HierarchyItemCollectionModel
+      _embedded:
+        type: object
+        required:
+          - elements
+        properties:
+          elements:
+            type: array
+            items:
+              $ref: './hierarchy_item_read_model.yml'

docs/api/apiv3/components/schemas/hierarchy_item_read_model.yml

@@ -0,0 +1,46 @@
+# Schema: HierarchyItemReadModel
+---
+type: object
+properties:
+  _type:
+    type: string
+    enum:
+      - HierarchyItem
+  id:
+    type: integer
+    description: Hierarchy item identifier
+  label:
+    type: string
+    description: The label of the hierarchy item
+  short:
+    type: string
+    description: The short name of the hierarchy item
+  depth:
+    type: integer
+    description: The hierarchy depth. The root item has a depth of 0.
+  _links:
+    type: object
+    properties:
+      self:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              This hierarchy item
+
+              **Resource**: HierarchyItem
+      parent:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The hierarchy item that is the parent of the current hierarchy item
+
+              **Resource**: HierarchyItem
+      children:
+        type: array
+        items:
+          allOf:
+            - $ref: './link.yml'
+            - description: |-
+                A hierarchy item that is a child of the current hierarchy item
+
+                **Resource**: HierarchyItem

docs/api/apiv3/openapi-spec.yml

@@ -186,6 +186,10 @@ paths:
     "$ref": "./paths/custom_action.yml"
   "/api/v3/custom_actions/{id}/execute":
     "$ref": "./paths/custom_action_execute.yml"
+  "/api/v3/custom_fields/{id}/items":
+    "$ref": "./paths/custom_field_items.yml"
+  "/api/v3/custom_field_items/{id}":
+    "$ref": "./paths/custom_field_item.yml"
   "/api/v3/custom_options/{id}":
     "$ref": "./paths/custom_option.yml"
   "/api/v3/days/non_working":
@@ -489,6 +493,12 @@ components:
       $ref: "./components/examples/grid-simple-response.yml"
     GroupResponse:
       $ref: "./components/examples/group-response.yml"
+    HierarchyItemCollectionFilteredResponse:
+      $ref: "./components/examples/hierarchy_item_collection_filtered_response.yml"
+    HierarchyItemCollectionResponse:
+      $ref: "./components/examples/hierarchy_item_collection_response.yml"
+    HierarchyItemResponse:
+      $ref: "./components/examples/hierarchy_item_response.yml"
     MembershipCreateRequestCustomMessage:
       $ref: "./components/examples/membership-create-request-custom-message.yml"
     MembershipCreateRequestGlobalRole:
@@ -673,6 +683,10 @@ components:
       "$ref": "./components/schemas/help_text_collection_model.yml"
     HelpTextModel:
       "$ref": "./components/schemas/help_text_model.yml"
+    HierarchyItemCollectionModel:
+      "$ref": "./components/schemas/hierarchy_item_collection_model.yml"
+    HierarchyItemReadModel:
+      "$ref": "./components/schemas/hierarchy_item_read_model.yml"
     Link:
       "$ref": "./components/schemas/link.yml"
     List_actionsModel:

docs/api/apiv3/paths/custom_field_item.yml

@@ -0,0 +1,49 @@
+# /api/v3/custom_field_items/{id}
+---
+get:
+  summary: Get a custom field hierarchy item
+  operationId: get_custom_field_item
+  description: |-
+    Retrieves a single custom field item specified by its unique identifier.
+  parameters:
+    - name: id
+      description: The custom field item's unique identifier
+      in: path
+      example: '42'
+      required: true
+      schema:
+        type: integer
+  responses:
+    '200':
+      description: OK
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/hierarchy_item_read_model.yml'
+          examples:
+            'simple response':
+              $ref: '../components/examples/hierarchy_item_response.yml'
+    '403':
+      description: Returned if the user is not logged in.
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          examples:
+            response:
+              value:
+                _type: Error
+                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
+                message: You are not authorized to access this resource.
+    '404':
+      description: Returned if the custom field item does not exist or the user is not logged in.
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          examples:
+            response:
+              value:
+                _type: Error
+                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+                message: The requested resource could not be found.