BitxorCore REST combina HTTP y WebSockets para realizar acciones de lectura y escritura en la cadena de bloques.
REST Gateway usa el puerto 3000 para HTTP y el puerto 3001 para HTTPS, y acepta solicitudes GET, PUT y POST.
Suponiendo que BitxorCore REST se ejecuta localmente, las solicitudes HTTP GET se pueden ejecutar desde un navegador y tener el formato:
http://localhost:3000/<path-to-API-request>
Las solicitudes PUT y POST tienen el mismo formato de consulta, pero usan estructuras JSON en el cuerpo de la solicitud. Este tipo de solicitud generalmente no se puede ejecutar desde el navegador a menos que use una extensi贸n.
Consulte la siguiente documentaci贸n para obtener la lista de puntos finales disponibles.
Para comprobar la compatibilidad entre la especificaci贸n de API y la implementaci贸n de REST Gateway, consulte Matriz de compatibilidad de productos.
Bitxor utiliza c贸digos de respuesta HTTP convencionales para indicar el 茅xito o el fracaso de una solicitud de API.
Los c贸digos en el rango 2xx indican 茅xito.
Los c贸digos en el rango 4xx indican que ocurri贸 un error con la informaci贸n proporcionada por el usuario.
Los c贸digos en el rango 5xx indican un error con el nodo.
Cuando una consulta devuelve m谩s de un resultado, REST Gateway pagina las respuestas de forma predeterminada. Los par谩metros de consulta se pueden personalizar para avanzar por las p谩ginas y filtrar el contenido devuelto.
Cada extremo paginable define su propio conjunto de filtros. Sin embargo, la siguiente tabla muestra los par谩metros de consulta presentes en cada punto final que se puede buscar:
tama帽op谩gina; entero [10..100]; Selecciona el n煤mero de entradas a devolver. Ejemplo: http://localhost:3000/blocks?pageSize=100 devuelve 100 entradas por p谩gina; 10numerodepagina; entero >=1; Filtra por n煤mero de p谩gina. Ejemplo: http://localhost:3000/blocks?page=2 devuelve la p谩gina 2; 1
desplazamiento; cadena (id); Identifica la entrada en la que se inicia la paginaci贸n. Ejemplo: http://localhost:3000/blocks?id=EE94FD819A1B30D6C5D1C03.;
orden; cadena {asc, desc}; Ordena las respuestas en orden ascendente o descendente seg煤n la propiedad de colecci贸n establecida en el par谩metro orderBy. Si la solicitud no especifica orderBy, REST devuelve la colecci贸n ordenada por id. Ejemplo: http://localhost:3000/blocks?order=asc devuelve las entradas del bloque en orden ascendente.; desc
ordenarPor; cadena; Elige el par谩metro por el que ordenar. De forma predeterminada, todas las colecciones se pueden ordenar por ID, pero la colecci贸n podr铆a definir propiedades adicionales.
Se pueden combinar varios par谩metros de consulta en la misma llamada.
Por ejemplo, http://localhost:3000/blocks?pageSize=100&id=EE94FD819A1B30D6C5D1C03 devolver谩 100 entradas de bloque por p谩gina que comenzar谩n con el ID de bloque EE94FD819A1B30D6C5D1C03.
Las respuestas tambi茅n incluyen metainformaci贸n sobre el n煤mero total de entradas de paginaci贸n, el n煤mero de p谩gina actual y el n煤mero total de p谩ginas. Aqu铆 hay un ejemplo de metainformaci贸n de respuesta de la paginaci贸n:
{
"data": [
{}
],
"pagination": {
"pageNumber": 0,
"pageSize": 0,
"totalEntries": 0,
"totalPages": 0
}
}
Para obtener actualizaciones en vivo cuando ocurre un evento en la cadena de bloques, BitxorCore REST publica WebSockets. Las aplicaciones cliente pueden abrir una conexi贸n WebSocket y obtener un identificador 煤nico. Con este identificador, las aplicaciones califican para suscribirse a los canales disponibles en lugar de sondear constantemente la API en busca de actualizaciones. Cuando ocurre un evento en un canal, REST Gateway env铆a una notificaci贸n a cada cliente suscrito en tiempo real.
Los URI de WebSocket comparten el mismo host y puerto que los URI de solicitudes HTTP, pero usan el protocolo ws://:
ws://localhost:3000/ws
Todos los canales comparten el mismo formato de respuesta, que es:
{
"topic": "{subscribed-channel}",
"data": {}
}
tema contiene el nombre del canal suscrito, por lo que se puede usar el mismo websocket para monitorear m煤ltiples canales (tema coincide con el campo subscribe proporcionado en el cuerpo de la solicitud al suscribirse).
datos es un objeto espec铆fico del canal. Cada canal enumerado a continuaci贸n describe el objeto de datos que devuelve.
bloquear
El canal block notifica a los clientes suscritos cada vez que se recolecta un nuevo bloque.
Cada mensaje devuelto contiene informaci贸n sobre un bloque recolectado.
Request body
{
"uid": "{uid}",
"subscribe": "block"
}
Datos de respuesta
bloque finalizado
El canal finalizedBlock notifica a los clientes suscritos cada vez que un conjunto de bloques es finalizado.
Cada mensaje devuelto contiene informaci贸n sobre el bloque m谩s alto en la ronda de finalizaci贸n. Todos los bloques con una altura menor se suponen finalizados.
Cuerpo de solicitud
{
"uid": "{uid}",
"subscribe": "finalizedBlock"
}
Response data
confirmadoAgregado/{direcci贸n}
El canal confirmedAdded notifica a los clientes suscritos cuando una transacci贸n relacionada con la direcci贸n dada se incluye en un bloque.
Cada mensaje devuelto contiene informaci贸n sobre una transacci贸n confirmada.
Request body
{
"uid": "{uid}",
"subscribe": "confirmedAdded/{address}"
}
Response data
agregado sin confirmar/{direcci贸n}
El canal unconfirmedAdded notifica a los clientes suscritos cuando una transacci贸n relacionada con la direcci贸n dada ingresa al estado no confirmado, esperando ser incluida en un bloque.
Cada mensaje devuelto contiene informaci贸n sobre una transacci贸n no confirmada.
Los escenarios posibles cuando se recibe este mensaje son: la transacci贸n se anuncia a la red a trav茅s del punto final HTTP PUT /transaction o una AggregateBondedTransaction tiene todos los cosignatarios requeridos y cambia su estado de parcial a sin confirmar.
Cuerpo de solicitud
{
"uid": "{uid}",
"subscribe": "unconfirmedAdded/{address}"
}
Datos de respuesta
sin confirmarEliminado/{direcci贸n}
El canal unconfirmedRemoved notifica a los clientes suscritos cuando una transacci贸n relacionada con la direcci贸n dada sale del estado no confirmado.
Cada mensaje devuelto contiene un hash de transacci贸n que ya no est谩 sin confirmar.
Los posibles escenarios cuando se recibe este mensaje son: la transacci贸n ahora est谩 confirmada o se alcanz贸 la fecha l铆mite y la transacci贸n no se incluy贸 en un bloque.
Cuerpo de solicitud
{
"uid":"{uid}",
"subscribe":"unconfirmedRemoved/{address}"
}
Response data
Hash
partialAdded/{address}
El canal partialAdded notifica a los clientes suscritos cuando una AggregateBondedTransaction relacionada con la direcci贸n dada ingresa al estado parcial, esperando que se completen todas las firmas conjuntas requeridas.
Cada mensaje devuelto contiene informaci贸n sobre una transacci贸n parcial agregada.
Request body
{
"uid": "{uid}",
"subscribe": "partialAdded/{address}"
}
Response data
partialRemoved/{address}
El canal partialRemoved notifica a los clientes suscritos cuando una transacci贸n relacionada con la direcci贸n dada sale del estado parcial.
Cada mensaje devuelto contiene un hash de transacci贸n parcial eliminado.
Los escenarios posibles cuando se emite este mensaje son: se recibieron todas las firmas conjuntas requeridas y la transacci贸n ahora no est谩 confirmada, o se alcanz贸 la fecha l铆mite y la transacci贸n no se incluy贸 en un bloque.
Cuerpo de solicitud
{
"uid": "{uid}",
"subscribe": "partialRemoved/{address}"
}
Response data
Hash
cosignature/{address}
El canal cosignature notifica a los clientes suscritos cuando se agrega una transacci贸n firmada por cosignatario relacionada con la direcci贸n dada a una AggregateBondedTransaction en el estado parcial.
Cada mensaje devuelto contiene una transacci贸n firmada conjuntamente.
Cuerpo de solicitud
{
"uid": "{uid}",
"subscribe": "cosignature/{address}"
}
Datos de respuesta
estado/{direcci贸n}
El canal status notifica a los clientes suscritos cuando una transacci贸n relacionada con la direcci贸n dada indica un error.
Cada mensaje devuelto contiene un mensaje de error y un hash de transacci贸n.
Cuerpo de solicitud
{
"uid": "{uid}",
"subscribe": "status/{address}"
}
Datos de respuesta
Last updated by John Doe
on 2023‑06‑19.
