API HTTP

Asset Core exposa APIs HTTP a través de dos daemons: el daemon d’escriptura per a les confirmacions i el daemon de lectura per a les consultes. Aquesta separació manté les escriptures deterministes i les lectures ràpides mentre preserva una única font de veritat.

Visió general

L’API és RESTful amb càrregues JSON i autenticació obligatòria amb token de portador. Ambdós daemons proporcionen punts d’entrada de salut per al monitoratge, i les respostes inclouen metadades de frescor quan sigui aplicable. Aquesta pàgina resumeix l’àrea superficial mentre que la referència OpenAPI proporciona el contracte complet.

Tots els punts d’entrada de dades estan espaiats sota /v1/write/namespaces/{namespace_id} i /v1/read/namespaces/{namespace_id}. Els espais de noms són el límit d’aïllament, així que incloeu l’espai de noms correcte en cada sol·licitud.

La especificació completa està disponible a la referència OpenAPI.

Estructura

Control del Pla d’Autenticació i Espai de Noms

Aquests punts finals permeten als operadors inspeccionar els principals, enumerar permisos i gestionar metadades de l’espai de noms. Utilitzeu-los per a fluxos de treball de governança i per verificar l’accés abans d’enviar compromisos.

Mètode	Camí	Descripció
GET	/v1/write/auth/whoami	Inspeccionar el principal actual
GET	/v1/write/auth/permissions	Llistar permisos per al token actual
GET	/v1/write/namespaces	Llistar espais de noms
GET	/v1/write/namespaces/{namespace_id}	Obtenir detalls de l’espai de noms
GET	/v1/write/namespaces/changes	Consultar el feed de canvis de l’espai de noms
GET	/v1/write/namespaces/status	Llistar instantànies d’estat de l’espai de noms
GET	/v1/write/namespaces/{namespace_id}/status	Obtenir l’estat de l’espai de noms
POST	/v1/write/namespaces/{namespace_id}/lifecycle	Proveir o eliminar un espai de noms
POST	/v1/write/namespaces/{namespace_id}/operational_state	Establir el mode operatiu de l’espai de noms
POST	/v1/write/namespaces/{namespace_id}/placement	Actualitzar metadades de col·locació
POST	/v1/write/namespaces/fork_from_snapshot	Fer un fork d’un espai de noms a partir d’una instantània

Punts d’escriptura amb abast de namespace

Aquests punts finals gestionen escriptures. commit/preflight és no mutador però utilitza les mateixes regles de validació que un compromís real. Sempre utilitzeu claus d’idempotència per a càrregues de treball de compromís en producció perquè els reintents siguin segurs.

Mètode	Camí	Descripció
POST	/v1/write/namespaces/{namespace_id}/commit	Enviar una transacció
POST	/v1/write/namespaces/{namespace_id}/commit/preflight	Validar una transacció sense mutació
POST	/v1/write/namespaces/{namespace_id}/commits/{commit_id}/reverse	Aplicar un pla de reversió emmagatzemat des del sidecar d’undo (verificat per conflictes)
POST	/v1/write/namespaces/{namespace_id}/register_class	Registrar una nova classe d’actius
POST	/v1/write/namespaces/{namespace_id}/register_class_shape	Registrar una forma per a una classe
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_1d	Registrar una forma contínua 1D
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_2d	Registrar una forma contínua 2D

Punts d’Accés de Lectura Amb Àmbit de Namespace

Els punts finals de lectura exposen projeccions derivades del registre de compromisos i inclouen metadades de frescor perquè pugueu raonar sobre l’anticuïtat.

Els punts finals de lectura seleccionats es detallen a continuació; consulteu la referència d’OpenAPI per al catàleg complet.

Mètode	Camí	Descripció
GET	/v1/read/namespaces/{namespace_id}/containers	Llistar contenidors
GET	/v1/read/namespaces/{namespace_id}/containers/{id}	Obtenir metadades del contenidor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/balances	Obtenir saldos del contenidor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/slots	Obtenir espais del contenidor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/cells	Obtenir col·locacions de la graella
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/free	Trobar espai lliure a la graella
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/contents	Contingut unificat del contenidor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_1d/placements	Col·locacions contínues 1D
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_2d/placements	Col·locacions contínues 2D
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/commits	Historial de compromisos del contenidor
GET	/v1/read/namespaces/{namespace_id}/commits	Historial de compromisos
GET	/v1/read/namespaces/{namespace_id}/classes	Llistar classes registrades
GET	/v1/read/namespaces/{namespace_id}/classes/stats	Estadístiques del registre de classes
GET	/v1/read/namespaces/{namespace_id}/classes/{id}	Obtenir detalls de la classe
GET	/v1/read/namespaces/{namespace_id}/classes/{id}/shapes	Obtenir formes de la classe
GET	/v1/read/namespaces/{namespace_id}/instances	Llistar instàncies
GET	/v1/read/namespaces/{namespace_id}/instances/{id}	Obtenir detalls de la instància
GET	/v1/read/namespaces/{namespace_id}/owners/{id}/summary	Resum de propietari
GET	/v1/read/namespaces/{namespace_id}/freshness	Obtenir metadades de frescor
GET	/v1/read/namespaces/{namespace_id}/replay	Reproduir esdeveniments del registre de compromisos
GET	/v1/read/namespaces/{namespace_id}/stream	Transmetre compromisos a través de SSE

Punts finals de salut global

Els punts finals de salut i mètriques estan dissenyats per a equilibradors de càrrega i sistemes de monitorització. Han de formar part de les seves comprovacions estàndard de desplegament.

Mètode	Camí	Descripció
GET	/v1/write/health	Escriure l’estat de salut del daemon
GET	/v1/read/health	Llegir l’estat de salut del daemon
GET	/v1/write/livez	Escriure la prova de viabilitat del daemon
GET	/v1/read/livez	Llegir la prova de viabilitat del daemon
GET	/v1/write/readyz	Escriure la prova de preparació del daemon
GET	/v1/read/readyz	Llegir la prova de preparació del daemon
GET	/v1/write/startupz	Escriure la prova d’inici del daemon
GET	/v1/read/startupz	Llegir la prova d’inici del daemon
GET	/v1/write/metrics	Escriure les mètriques Prometheus del daemon (escolta quan està habilitada)
GET	/v1/read/metrics	Llegir les mètriques Prometheus del daemon (escolta quan està habilitada)

Campanyes

Encapsulaments de sol·licitud

Header	Required	Description
Authorization	Sí	Token Bearer per al principal actual
Content-Type	Sí	Ha de ser application/json per a les sol·licituds POST
x-assetcore-namespace	Condicional	Namespace per llegir punts d’entrada de salut/prova quan no està configurat
x-assetcore-min-world-seq	No	Requereix projecció per assolir una seqüència mínima del món
x-correlation-id	No	ID de correlació del client per al seguiment

Encapsulaments de resposta

Header	Description
x-asset-idempotency	hit si la resposta es va servir des de la memòria cau d’idempotència
Content-Type	Sempre application/json

Camps de resposta comuns

Les respostes d’èxit inclouen:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 42,
  "world_seq_end": 42,
  "event_count": 2,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "echo": { ... }
}

Les respostes de prevol inclouen: status, executed_ops, failed_op_index, op_outcomes, i validated_world_seq. Vegeu Prevol i Compromís Invers per a la semàntica.

Les respostes de consulta inclouen frescor:

{
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "freshness": {
    "namespace": 5001,
    "world_seq": 42,
    "commit_log_world_seq": 45,
    "lag": 3,
    "lag_ms": 125
  }
}

Exemples

Enviar una transacció

curl -X POST http://localhost:8080/v1/write/namespaces/5001/commit \
  -H "Authorization: Bearer $ASSETCORE_WRITE_TOKEN" \
  -H "x-correlation-id: doc-example-2026-01-15" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": { "type": "balance" },
          "owner": null,
          "policies": null
        }
      }
    ],
    "idempotency_key": "create-container-2026-01-15"
  }'

Resposta:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 1,
  "world_seq_end": 1,
  "event_count": 1,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "client_correlation_id": "doc-example-2026-01-15",
  "echo": {
    "idempotency_key": "create-container-2026-01-15"
  },
  "created_entities": {
    "containers": [1001]
  }
}

Consulta de Saldo de Contenidors

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://localhost:8081/v1/read/namespaces/5001/containers/1001/balances

Resposta:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "freshness": {
    "namespace": 5001,
    "world_seq": 1,
    "commit_log_world_seq": 1,
    "lag": 0,
    "lag_ms": 0
  }
}

Comprovar la salut

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://localhost:8080/v1/write/health

Resposta:

{
  "status": "healthy",
  "version": "0.1.0",
  "api_version": "0.1.0",
  "build_git_sha": "abc123",
  "uptime_secs": 3600
}

Referències relacionades

• Transactions - Estructura del cos de la sol·licitud
• Model d’Error - Codis d’estat i respostes d’error
• Prevol i Compromís Invers - Validació no mutadora i semàntica d’undo
• OpenAPI Specification - Contracte HTTP canònic