API HTTP

Asset Core expone APIs HTTP a través de dos daemons: el daemon de escritura para commits y el daemon de lectura para consultas.

Visión general

La API es RESTful con cargas útiles en JSON. Ambos demonios proporcionan puntos finales de salud para monitoreo, y las respuestas incluyen metadatos de frescura cuando es aplicable.

La especificación completa está disponible en openapi.json en el paquete de distribución.

Estructura

Escribir Puntos Finales del Daemon

Método	Ruta	Descripción
POST	/v1/commit	Enviar una transacción
POST	/v1/register/class	Registrar una nueva clase de activo
POST	/v1/register/class-shape	Registrar una forma para una clase
GET	/v1/health	Verificación de salud con estado del registro de confirmaciones
GET	/v1/metrics	Métricas de Prometheus

Leer Puntos Finales del Daemon

Método	Ruta	Descripción
GET	/v1/read/container/{id}	Obtener metadatos del contenedor
GET	/v1/read/container/{id}/balances	Obtener saldos del contenedor
GET	/v1/read/container/{id}/slots	Obtener espacios del contenedor
GET	/v1/read/container/{id}/grid	Obtener cuadrícula del contenedor
GET	/v1/read/class/{id}	Obtener detalles de la clase
GET	/v1/read/classes	Listar clases registradas
GET	/v1/read/class/{id}/shapes	Obtener formas de la clase
GET	/v1/read/class/{id}/stats	Obtener estadísticas de la clase
GET	/v1/read/freshness	Obtener metadatos de frescura
GET	/v1/health	Verificación de salud

Campos

Encabezados de Solicitud

Encabezado	Requerido	Descripción
Content-Type	Sí	Debe ser application/json para solicitudes POST
X-Idempotency-Key	No	Alternativa al campo del cuerpo de la solicitud

Encabezados de Respuesta

Encabezado	Descripción
X-Asset-Idempotency	hit si la respuesta fue almacenada en caché
Content-Type	Siempre application/json

Campos de Respuesta Comunes

Las respuestas de éxito incluyen:

{
  "global_seq": 42,
  "batch_seq": 1,
  "minted_instances": [9001, 9002],
  "metadata": { ... }
}

Las respuestas a las consultas incluyen frescura:

{
  "data": { ... },
  "freshness": {
    "checkpoint_seq": 42,
    "commit_log_seq": 45
  }
}

Ejemplos

Enviar una Transacción

curl -X POST http://localhost:8080/v1/commit \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": "Standard",
          "owner": null
        }
      }
    ],
    "idempotency_key": "create-container-1001"
  }'

Respuesta:

{
  "global_seq": 1,
  "batch_seq": 1,
  "minted_instances": [],
  "metadata": {
    "idempotency_key": "create-container-1001"
  }
}

Consultar Saldos de Contenedores

curl http://localhost:8081/v1/read/container/1001/balances

Respuesta:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "freshness": {
    "checkpoint_seq": 1,
    "commit_log_seq": 1
  }
}

Verificar Salud

curl http://localhost:8080/v1/health

Respuesta:

{
  "status": "healthy",
  "commit_log": {
    "end_seq": 100,
    "checkpoint_seq": 100,
    "lag": 0,
    "driver": {
      "name": "file",
      "path": "/var/lib/assetcore/commit_log.log"
    }
  }
}

Referencias relacionadas

• Transacciones - Estructura del cuerpo de la solicitud
• Modelo de Error - Códigos de estado y respuestas de error
• Especificación OpenAPI - Especificación completa de la API