Skip to content

entities.md

Latest commit

 

History

History
467 lines (362 loc) · 12.9 KB

entities.md

File metadata and controls

467 lines (362 loc) · 12.9 KB
Raw
title Entities
description Understand Entities - instances of Entity Templates with actual data

Entities are instances of Entity Templates containing actual data. If an Entity Template is the blueprint, an Entity is the house built from that blueprint.

Overview

An Entity contains:

  • Identity - Unique identifier and name
  • Template Reference - Which template it instantiates
  • Properties - Actual values for the template's property definitions
  • Relations - Links to other entities
flowchart LR
    subgraph Template["Entity Template: sonar_project"]
        PT[properties_definitions]
        RT[relations_definitions]
    end

    subgraph Entity["Entity: my-backend-project"]
        PE[properties: project_name, loc, issues]
        RE[relations: github_repository]
    end

    Template -->|instantiates| Entity
Loading

Structure

Complete Example

Here's an entity instantiated from the web-service template:

{
  "identifier": "my-web-service",
  "name": "my-web-service",
  "template_identifier": "web-service",
  "properties": {
    "port": "8080",
    "environment": "dev"
  },
  "relations": {
    "depends-on": [
      {
        "identifier": "web-api-1",
        "name": "Web API 1",
        "template_identifier": "web-service"
      }
    ]
  }
}

Core Fields

Field Type Description
identifier String Unique identifier within the template scope
name String Human-readable name
template_identifier String The Entity Template this entity instantiates
properties Object Key-value pairs of property data
relations Object Links to other entities (grouped by name)

Creating an Entity

You create an entity by sending a POST request to the entities endpoint, specifying the template identifier in the URL path.

Endpoint

POST /api/v1/entities/{templateIdentifier}

Request Body

{
  "name": "my-web-service",
  "identifier": "my-web-service",
  "properties": {
    "port": "8080",
    "environment": "dev"
  },
  "relations": [
    {
      "name": "depends-on",
      "target_entity_identifiers": [
        "web-api-1",
        "web-api-2"
      ]
    }
  ]
}

Validation

IDP-Core validates entities at two levels: syntactic validation at the API boundary and semantic validation against the template definition.

Syntactic Validation (API Layer)

The API enforces basic structural rules on the request body before any business logic runs:

Field Rule Error Message
name Required, not blank Entity name is mandatory
identifier Required, not blank Entity identifier is mandatory
relations[].name Required, not blank Relation name is mandatory
relations[].target_entity_identifiers Required, not null Relation target identifiers required

If any rule fails, the API returns 400 Bad Request with a description of the violation.

Semantic Validation (Domain Layer)

After syntactic checks pass, the domain service validates the entity against its template definition:

  • Template existence - The template identifier must match an existing template. Returns 404 Not Found if the template does not exist.
  • Property value types - Values must conform to the property definition type (STRING, NUMBER, BOOLEAN).
  • Property rules - Values must satisfy the template's property rules (min/max length, format, regex, enum).
  • Required properties - All properties marked as required in the template must be present.
  • Relation names - Each provided relation must exist in the template relation definitions.
  • Relation constraints - Required relations must be present, and non-to_many relations can target only one entity.
  • Duplicate check - An entity with the same identifier must not already exist for the template. Returns 409 Conflict if it does.

Response Codes

Code Description
201 Entity created successfully
400 Invalid request body or validation failure
401 Missing or invalid authentication token
403 Insufficient permissions
404 Template not found for the given identifier
409 An entity with this identifier already exists for the template
500 Unexpected server error

Minimal Example

You can create an entity with only the required fields:

{
  "name": "microservice-minimal",
  "identifier": "microservice-minimal"
}

Properties and relations are optional in the request body. The domain layer validates that all required properties (as defined in the template) are present.

Properties

Properties contain the actual data values. The structure follows the template's property definitions:

{
  "properties": {
    "project_name": "My Backend Project",
    "issues_number": 137,
    "loc": 20000,
    "last_analysis_date": "2025-11-28..."
  }
}

Validation of properties

The system validates values against the template's property rules:

  • Required properties must be present
  • Types must match: STRING, NUMBER, or BOOLEAN
  • Enforcement rules apply: min or max length, format, enum values

Relations

Relations link entities together, forming a graph. Each relation references the entity identifiers of related entities.

Creating Relations

When creating an entity, you specify relations as an array of objects, each with a name and a list of target_entity_identifiers:

{
  "relations": [
    {
      "name": "depends-on",
      "target_entity_identifiers": [
        "web-api-1",
        "web-api-2"
      ]
    },
    {
      "name": "owned-by",
      "target_entity_identifiers": [
        "platform-team"
      ]
    }
  ]
}

One-to-Many Relations (to_many: true)

When multiple related entities are allowed, list several identifiers:

{
  "relations": [
    {
      "name": "components",
      "target_entity_identifiers": [
        "frontend",
        "backend",
        "database"
      ]
    }
  ]
}

Relations in Responses

In API responses, relations groups both outbound (targets) and inbound (sources) relations by name and includes summary information about each related entity (including template_identifier).

{
  "relations": {
    "depends-on": [
      {
        "identifier": "web-api-1",
        "name": "Web API 1",
        "template_identifier": "web-service"
      },
      {
        "identifier": "web-api-2",
        "name": "Web API 2",
        "template_identifier": "web-service"
      }
    ]
  }
}

Retrieving Entities

List Entities by Template

Retrieve a paginated list of entities for a given template:

GET /api/v1/entities/{templateIdentifier}?page=0&size=20&sort=identifier,asc

Get Entity by Identifier

Retrieve a specific entity using its template and entity identifiers:

GET /api/v1/entities/{templateIdentifier}/{entityIdentifier}

Updating an Entity

You update an existing entity by sending a PUT request on the entity resource path.

Update Endpoint

PUT /api/v1/entities/{templateIdentifier}/{entityIdentifier}

Update Request Body

The request body has a similar shape and validation rules as POST /api/v1/entities/{templateIdentifier}, except the entity identifier is only present in path parameters.

{
  "name": "my-web-service-updated",
  "properties": {
    "applicationName": "catalog-api",
    "ownerEmail": "owner@example.com",
    "port": "8080",
    "environment": "DEV",
    "version": "1.2.3",
    "teamName": "platform-team",
    "baseUrl": "https://catalog.example.com",
    "protocol": "HTTP",
    "programmingLanguage": "JAVA"
  },
  "relations": [
    {
      "name": "depends-on",
      "target_entity_identifiers": [
        "web-api-1"
      ]
    }
  ]
}

Update Example Request

curl -X PUT http://localhost:8084/api/v1/entities/web-service/my-web-service \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-web-service-updated",
    "properties": {
      "applicationName": "catalog-api",
      "ownerEmail": "owner@example.com",
      "port": "8080",
      "environment": "DEV",
      "version": "1.2.3",
      "teamName": "platform-team",
      "baseUrl": "https://catalog.example.com",
      "protocol": "HTTP",
      "programmingLanguage": "JAVA"
    }
  }'

Update Example Response

{
  "name": "my-web-service-updated",
  "template_identifier": "web-service",
  "properties": {
    "applicationName": "catalog-api",
    "ownerEmail": "owner@example.com",
    "port": "8080",
    "environment": "DEV",
    "version": "1.2.3",
    "teamName": "platform-team",
    "baseUrl": "https://catalog.example.com",
    "protocol": "HTTP",
    "programmingLanguage": "JAVA"
  },
  "relations": {}
}

Partially Updating an Entity

Use PATCH when only selected fields should change. Fields omitted from the request remain unchanged. Properties and relations supplied in the request are merged with the existing values by name.

PATCH /api/v1/entities/{templateIdentifier}/{entityIdentifier}

curl -X PATCH http://localhost:8084/api/v1/entities/web-service/my-web-service \
  -H "Content-Type: application/json" \
  -d '{"properties": {"port": "9090"}}'

Patch Response Codes

Code Description
200 Entity updated successfully
400 Invalid request body or validation failure
401 Missing or invalid authentication token
403 Insufficient permissions
404 Template or entity not found for the given identifier
500 Unexpected server error

Deleting an Entity

You delete an entity by sending a DELETE request to the entity resource path.

Delete Endpoint

DELETE /api/v1/entities/{templateIdentifier}/{entityIdentifier}

Delete Example Request

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:

Warning

The second-level JSON paths (properties, relations) are not guaranteed by the API contract. Their structure depends on the template configuration.

This means:

  • Properties change when templates change
  • Clients should handle unknown properties gracefully

Next Steps