API HTTP

Asset Core exposa APIs HTTP a través de dos daemons: el daemon d’escriptura per a commits i el daemon de lectura per a consultes.

Visió general

L’API és RESTful amb càrregues útils JSON. Ambdós daemons proporcionen punts d’extrem de salut per al monitoratge, i les respostes inclouen metadades de frescor quan és aplicable.

La especificació completa està disponible a openapi.json en el paquet de distribució.

Estructura

Escriure punts finals del daemon

Mètode	Ruta	Descripció
POST	/v1/commit	Enviar una transacció
POST	/v1/register/class	Registrar una nova classe d’actius
POST	/v1/register/class-shape	Registrar una forma per a una classe
GET	/v1/health	Comprovació de salut amb l’estat del registre de transaccions
GET	/v1/metrics	Mètriques de Prometheus

Llegir els punts finals del daemon

Mètode	Ruta	Descripció
GET	/v1/read/container/{id}	Obtenir metadades del contenidor
GET	/v1/read/container/{id}/balances	Obtenir balances del contenidor
GET	/v1/read/container/{id}/slots	Obtenir espais del contenidor
GET	/v1/read/container/{id}/grid	Obtenir graella del contenidor
GET	/v1/read/class/{id}	Obtenir detalls de la classe
GET	/v1/read/classes	Llistar classes registrades
GET	/v1/read/class/{id}/shapes	Obtenir formes de la classe
GET	/v1/read/class/{id}/stats	Obtenir estadístiques de la classe
GET	/v1/read/freshness	Obtenir metadades de frescor
GET	/v1/health	Comprovació de salut

Camps

Encapsulaments de sol·licitud

Header	Required	Description
Content-Type	Sí	Ha de ser application/json per a les sol·licituds POST
X-Idempotency-Key	No	Alternativa al camp del cos de la sol·licitud

Encapsulaments de resposta

Header	Descripció
X-Asset-Idempotency	hit si la resposta va ser emmagatzemada
Content-Type	Sempre application/json

Camps de resposta comuns

Les respostes d’èxit inclouen:

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

Les respostes de consulta inclouen frescor:

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

Exemples

Enviar una transacció

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

Resposta:

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

Consulta de Saldo de Contenidors

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

Resposta:

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

Comprovar la salut

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

Resposta:

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

Referències relacionades

• Transactions - Estructura del cos de la sol·licitud
• Model d’Error - Codis d’estat i respostes d’error
• Especificació OpenAPI - Especificació completa de l’API