API

Previous Next

Статус: Draft Дата: 2026-04-29

1. API principles

  • API является product-facing для UI и internal-facing для core-сервисов.
  • Долгие действия возвращают ссылку на control-plane-service, а не исполняются здесь.
  • Mutating commands должны поддерживать idempotency key и expected_version.
  • Сложные графы читаются из read models.

2. API groups

Resources

1
2
3
4
5
6
7
8
GET  /v1/resources
GET  /v1/resources/{resource_id}
POST /v1/resources
PATCH /v1/resources/{resource_id}
GET  /v1/resources/{resource_id}/relationships
GET  /v1/resources/{resource_id}/capabilities
GET  /v1/resources/{resource_id}/health
GET  /v1/resources/{resource_id}/operations-summary

Resource types

1
2
GET  /v1/resource-types
GET  /v1/resource-types/{type_key}

Topology

1
2
3
4
5
GET  /v1/topology/regions
GET  /v1/topology/datacenters
GET  /v1/topology/layers
GET  /v1/topology/segments
GET  /v1/topology/graph

Capabilities

1
2
3
4
GET  /v1/capabilities/definitions
GET  /v1/capabilities/definitions/{capability_key}
GET  /v1/capabilities/providers
GET  /v1/capabilities/graph

Graph queries

1
2
3
GET /v1/graphs/resources
GET /v1/graphs/topology
GET /v1/graphs/capabilities

Internal commands from control-plane

1
2
3
POST /internal/v1/resources/{resource_id}/apply-operation-result
POST /internal/v1/resources/{resource_id}/provided-capabilities
POST /internal/v1/resources/{resource_id}/health-observations

3. ResourceUpdateCommand

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
resource_update_command:
  command_id: uuid
  idempotency_key: string
  operation_id: uuid
  resource_id: string
  expected_version: integer
  changes:
    lifecycle_status: running
    health_status: healthy
    desired_state_patch: {}
    observed_state_patch: {}
    relationship_changes: []
    provided_capability_changes: []
  evidence_refs:
    - evidence-ref

Rules:

  • reject if expected_version does not match;
  • reject if command is not idempotent and command_id already exists with different payload;
  • store operation reference but do not import full operation history.

4. Error categories

1
2
3
4
5
6
7
8
not_found
version_conflict
validation_error
policy_denied
unsupported_resource_type
invalid_capability
stale_projection
internal_error
Обзор Модель данных