API HTTP

Asset Core expone APIs HTTP a través de dos demonios: el demonio de escritura para los commits y el demonio de lectura para las consultas. Esta separación mantiene las escrituras deterministas y las lecturas rápidas, al tiempo que preserva una única fuente de verdad.

Resumen

La API es RESTful con cargas útiles JSON y autenticación obligatoria mediante token portador. Ambos demonios proporcionan puntos finales de salud para monitoreo, y las respuestas incluyen metadatos de frescura cuando sea aplicable. Esta página resume el área superficial mientras que la referencia de OpenAPI proporciona el contrato completo.

Todos los puntos finales de datos están agrupados bajo /v1/write/namespaces/{namespace_id} y /v1/read/namespaces/{namespace_id}. Los espacios de nombres son el límite de aislamiento, así que incluye el espacio de nombres correcto en cada solicitud.

La especificación completa está disponible en la referencia de OpenAPI.

Estructura

Control de Autenticación y Espacio de Nombres

Estos puntos finales permiten a los operadores inspeccionar los principales, enumerar permisos y gestionar metadatos de espacio de nombres. Úselos para flujos de trabajo de gobernanza y para verificar el acceso antes de enviar confirmaciones.

Método	Ruta	Descripción
GET	/v1/write/auth/whoami	Inspeccionar el principal actual
GET	/v1/write/auth/permissions	Listar permisos para el token actual
GET	/v1/write/namespaces	Listar espacios de nombres
GET	/v1/write/namespaces/{namespace_id}	Obtener detalles del espacio de nombres
GET	/v1/write/namespaces/changes	Consultar el feed de cambios del espacio de nombres
GET	/v1/write/namespaces/status	Listar instantáneas del estado del espacio de nombres
GET	/v1/write/namespaces/{namespace_id}/status	Obtener el estado del espacio de nombres
POST	/v1/write/namespaces/{namespace_id}/lifecycle	Provisionar o eliminar un espacio de nombres
POST	/v1/write/namespaces/{namespace_id}/operational_state	Establecer el modo operativo del espacio de nombres
POST	/v1/write/namespaces/{namespace_id}/placement	Actualizar los metadatos de colocación
POST	/v1/write/namespaces/fork_from_snapshot	Crear un fork de un espacio de nombres desde una instantánea

Puntos finales de escritura con alcance de espacio de nombres

Estos puntos finales manejan escrituras. commit/preflight no muta, pero utiliza las mismas reglas de validación que un commit real. Siempre utiliza claves de idempotencia para las cargas de trabajo de commit en producción para que los reintentos sean seguros.

Método	Ruta	Descripción
POST	/v1/write/namespaces/{namespace_id}/commit	Enviar una transacción
POST	/v1/write/namespaces/{namespace_id}/commit/preflight	Validar una transacción sin mutación
POST	/v1/write/namespaces/{namespace_id}/commits/{commit_id}/reverse	Aplicar un plan de reversión almacenado desde el sidecar de deshacer (verificado por conflictos)
POST	/v1/write/namespaces/{namespace_id}/register_class	Registrar una nueva clase de activo
POST	/v1/write/namespaces/{namespace_id}/register_class_shape	Registrar una forma para una clase
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_1d	Registrar una forma continua 1D
POST	/v1/write/namespaces/{namespace_id}/register_class_continuous_shape_2d	Registrar una forma continua 2D

Puntos finales de lectura con ámbito de espacio de nombres

Los puntos finales de lectura exponen proyecciones derivadas del registro de confirmaciones e incluyen metadatos de frescura para que puedas razonar sobre la obsolescencia.

Los puntos finales de lectura seleccionados se enumeran a continuación; consulte la referencia de OpenAPI para el catálogo completo.

Método	Ruta	Descripción
GET	/v1/read/namespaces/{namespace_id}/containers	Listar contenedores
GET	/v1/read/namespaces/{namespace_id}/containers/{id}	Obtener metadatos del contenedor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/balances	Obtener saldos del contenedor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/slots	Obtener espacios del contenedor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/cells	Obtener ubicaciones de la cuadrícula
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/grid/free	Encontrar espacio libre en la cuadrícula
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/contents	Contenido unificado del contenedor
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_1d/placements	Ubicaciones continuas 1D
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/continuous_2d/placements	Ubicaciones continuas 2D
GET	/v1/read/namespaces/{namespace_id}/containers/{id}/commits	Historial de confirmaciones del contenedor
GET	/v1/read/namespaces/{namespace_id}/commits	Historial de confirmaciones
GET	/v1/read/namespaces/{namespace_id}/classes	Listar clases registradas
GET	/v1/read/namespaces/{namespace_id}/classes/stats	Estadísticas del registro de clases
GET	/v1/read/namespaces/{namespace_id}/classes/{id}	Obtener detalles de la clase
GET	/v1/read/namespaces/{namespace_id}/classes/{id}/shapes	Obtener formas de la clase
GET	/v1/read/namespaces/{namespace_id}/instances	Listar instancias
GET	/v1/read/namespaces/{namespace_id}/instances/{id}	Obtener detalles de la instancia
GET	/v1/read/namespaces/{namespace_id}/owners/{id}/summary	Resumen del propietario
GET	/v1/read/namespaces/{namespace_id}/freshness	Obtener metadatos de frescura
GET	/v1/read/namespaces/{namespace_id}/replay	Reproducir eventos del registro de confirmaciones
GET	/v1/read/namespaces/{namespace_id}/stream	Transmitir confirmaciones a través de SSE

Puntos finales de salud global

Los puntos finales de salud y métricas están diseñados para equilibradores de carga y sistemas de monitoreo. Deben ser parte de sus verificaciones estándar de implementación.

Método	Ruta	Descripción
GET	/v1/write/health	Escribir estado de salud del daemon
GET	/v1/read/health	Leer estado de salud del daemon
GET	/v1/write/livez	Escribir prueba de vivacidad del daemon
GET	/v1/read/livez	Leer prueba de vivacidad del daemon
GET	/v1/write/readyz	Escribir prueba de disponibilidad del daemon
GET	/v1/read/readyz	Leer prueba de disponibilidad del daemon
GET	/v1/write/startupz	Escribir prueba de inicio del daemon
GET	/v1/read/startupz	Leer prueba de inicio del daemon
GET	/v1/write/metrics	Escribir métricas de Prometheus del daemon (escucha cuando está habilitado)
GET	/v1/read/metrics	Leer métricas de Prometheus del daemon (escucha cuando está habilitado)

Campos

Encabezados de Solicitud

Encabezado	Requerido	Descripción
Authorization	Sí	Token Bearer para el principal actual
Content-Type	Sí	Debe ser application/json para solicitudes POST
x-assetcore-namespace	Condicional	Espacio de nombres para leer puntos finales de salud/probe cuando no está configurado
x-assetcore-min-world-seq	No	Requiere proyección para alcanzar una secuencia mínima del mundo
x-correlation-id	No	ID de correlación del cliente para rastreo

Encabezados de Respuesta

Encabezado	Descripción
x-asset-idempotency	hit si la respuesta fue servida desde la caché de idempotencia
Content-Type	Siempre application/json

Campos de Respuesta Comunes

Las respuestas de éxito incluyen:

{
  "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": { ... }
}

Las respuestas de pre-vuelo incluyen: status, executed_ops, failed_op_index, op_outcomes, y validated_world_seq. Consulte Preflight and Reverse Commit para obtener la semántica.

Las respuestas a las consultas incluyen frescura:

{
  "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
  }
}

Ejemplos

Enviar una Transacción

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"
  }'

Respuesta:

{
  "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]
  }
}

Consultar Saldos de Contenedores

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

Respuesta:

{
  "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
  }
}

Verificar Salud

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

Respuesta:

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

Referencias relacionadas

• Transacciones - Estructura del cuerpo de la solicitud
• Modelo de Error - Códigos de estado y respuestas de error
• Prevuelo y Compromiso Inverso - Validación no mutante y semántica de deshacer
• Especificación OpenAPI - Contrato HTTP canónico