feat(core): DELETE entity endpoint

docs/src/concepts/entities.md

@@ -404,6 +404,59 @@ curl -X PUT http://localhost:8084/api/v1/entities/web-service/my-web-service \
 
 ---
 
+## Deleting an Entity
+
+You delete an entity by sending a `DELETE` request to the entity resource path.
+
+### Delete Endpoint
+
+```text
+DELETE /api/v1/entities/{templateIdentifier}/{entityIdentifier}
+```
+
+### Delete Example Request
+
+```bash
+curl -X DELETE http://localhost:8084/api/v1/entities/web-service/my-web-service \
+  -H "Content-Type: application/json"
+```
+
+### Delete Response Codes
+
+| Code  | Description                                            |
+|-------|--------------------------------------------------------|
+| `204` | Entity deleted successfully                            |
+| `400` | Invalid identifiers or deletion not allowed            |
+| `401` | Missing or invalid authentication token                |
+| `403` | Insufficient permissions                               |
+| `404` | Template or entity not found for the given identifier  |
+| `409` | Target entity has required relations                   |
+| `500` | Unexpected server error                                |
+
+### Delete Behavior
+
+When an entity is deleted, IDP-Core automatically manages relation cleanup to maintain referential integrity:
+
+- **Direct deletion**: The entity and all its relations are removed from the system
+- **Cascade cleanup**: Any relations from other entities that reference the deleted entity are automatically removed from those parent entities
+- **Data integrity**: The system ensures no dangling references remain after deletion
+
+#### Example: Cascade Cleanup
+
+If you have:
+
+- Entity A with a relation "depends-on" targeting Entity B
+- Entity B with a relation "owns" targeting Entity C
+
+When you delete Entity B:
+
+1. Entity B is removed completely
+2. Entity A's "depends-on" relation is automatically cleaned up (removing the reference to B)
+3. Entity B's "owns" relation to Entity C is removed
+4. Entity C remains untouched (no incoming relations)
+
+---
+
 ## Dynamic Schema
 
 Because templates are configured at runtime, the entity structure is **dynamic**:

docs/src/static/swagger.yaml

@@ -411,6 +411,56 @@ paths:
             '*/*':
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+    delete:
+      tags:
+        - Entities Management
+      summary: Delete an existing entity
+      description: Delete an entity from the system using its template and entity identifiers. This operation removes the entity and automatically cleans up any relations from other entities that reference it.
+      operationId: deleteEntity
+      parameters:
+        - name: templateIdentifier
+          in: path
+          required: true
+          schema:
+            minLength: 1
+            type: string
+        - name: entityIdentifier
+          in: path
+          required: true
+          schema:
+            minLength: 1
+            type: string
+      responses:
+        '204':
+          description: Entity deleted successfully
+        '400':
+          description: Invalid identifiers provided
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized - Missing or invalid token
+        '403':
+          description: Insufficient rights
+        '404':
+          description: Entity or template not found with the provided identifier
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          description: Target entity has required relations
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Unexpected server-side failure
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
 components:
   schemas:
     EntityTemplateUpdateDtoIn:

src/main/java/com/decathlon/idp_core/domain/constant/ValidationMessages.java

@@ -66,6 +66,7 @@ public class ValidationMessages {
   public static final String ENTITY_NOT_FOUND = "Entity not found with template identifier %s and entity identifier '%s'";
   public static final String ENTITY_ALREADY_EXISTS = "Entity with name '%s' already exists for template '%s'";
   public static final String ENTITY_VALIDATION_FAILED = "Entity validation failed: ";
+  public static final String ENTITY_DELETION_BLOCKED = "Cannot delete entity '%s' (template: '%s') because it is referenced by required relations in the following entities: %s. Please update the relation definitions to make them optional or remove the required constraint before deleting this entity.";
 
   // Helper method to construct rules incompatibility message
   public static String rulesAreIncompatible(String rule1, String rule2) {

src/main/java/com/decathlon/idp_core/domain/exception/entity/EntityDeletionBlockedException.java

@@ -0,0 +1,39 @@
+package com.decathlon.idp_core.domain.exception.entity;
+
+import static com.decathlon.idp_core.domain.constant.ValidationMessages.ENTITY_DELETION_BLOCKED;
+
+import java.util.List;
+
+/// Domain exception for blocked Entity deletion due to required relations.
+///
+/// **Business purpose:** Represents the business rule violation when attempting
+/// to delete an Entity that is still referenced by required relations in other entities.
+/// This enforces the business invariant that required relations must be satisfied before
+/// entity deletion is allowed.
+///
+/// **Why this exception exists:**
+/// - Enforces referential integrity and required relation constraints
+/// - Prevents dangling required references that would leave entities in invalid states
+/// - Provides detailed context about which entities/relations block the deletion
+/// - Guides users on how to resolve the blocking constraint (update template or remove required flag)
+public class EntityDeletionBlockedException extends RuntimeException {
+
+  /// Constructs a new exception with entity and blocking relation details.
+  ///
+  /// **Why this exists:** Provides comprehensive error message that includes:
+  /// - The entity being deleted (identifier and template)
+  /// - The list of entities that have required relations to it
+  /// - Actionable guidance on how to resolve the issue
+  ///
+  /// @param templateIdentifier the template identifier of the entity being
+  /// deleted
+  /// @param entityIdentifier the identifier of the entity being deleted
+  /// @param blockingEntities list of entity identifiers that have required
+  /// relations to the deleted entity
+  public EntityDeletionBlockedException(String templateIdentifier, String entityIdentifier,
+      List<String> blockingEntities) {
+    super(String.format(ENTITY_DELETION_BLOCKED, entityIdentifier, templateIdentifier,
+        String.join(", ", blockingEntities)));
+  }
+
+}

src/main/java/com/decathlon/idp_core/domain/port/EntityRepositoryPort.java

@@ -52,4 +52,9 @@ void deletePropertiesByTemplateIdentifierAndPropertyName(String templateIdentifi
 
   void deleteRelationsByTemplateIdentifierAndRelationName(String templateIdentifier,
       Collection<String> relationNames);
+
+  List<Entity> findEntitiesRelated(String targetIdentifier);
+
+  void deleteByTemplateIdentifierAndIdentifier(String templateIdentifier, String entityIdentifier);
+
 }