Documento original Publicado el 18 de Diciembre de 2018
Ver link a IOHK de Matthias Benkort, Desarrollador de Haskell
Ver Documento Original aquí.
Matthias Benkort y Jacob Mitchell cubren las novedades.
En este blog, Matthias Benkort, líder de la API de billetera, explica los cambios en la API de billetera de Cardano que se están produciendo en Cardano 1.4, y Jacob Mitchell, líder de devOps, muestran cómo construir un cliente Cardano con la antigua API de billetera V0 y la nueva API de billetera V1, en lugar de la opción predeterminada que proporciona sólo la nueva API.
Esta entrada de blog está dirigida principalmente a los usuarios actuales de la API de Cardano para billeteras; en particular, a aquellos que ya se han integrado con la versión beta de la API V1 antes de Cardano 1.4.
La API de la billetera Cardano tiene su propio versionado. A partir de Cardano 1.4 la anterior API para billeteras V0 quedará obsoleta. Todos los terminales V0 API REST han sido portados a V1 API, y la reescritura de la billetera le dio al equipo de la billetera la oportunidad de corregir y mejorar la semántica de la billetera de Cardano. Como resultado, ha habido cuatro cambios de ruptura como se describe a continuación. La API para billetera V1 se convertirá en la API para billetera por defecto en Cardano 1.4.
-
La estructura de diagnóstico del error NotEnoughMoney (Sin Dinero Suficiente) se ha modificado para dar cabida a más casos.
-
La estructura de diagnóstico del error WalletAlready Exists (Billetera ya existe) se ha modificado para proporcionar el campo adicional WalletId (Identificacion de Billetera) para el ID de la billetera preexistente.
-
El comportamiento de /api/v1/addresses/{addresses} (ADDRESSES = DIRECCIONES) se ha ajustado para reflejar con mayor precisión la semántica de la propiedad con respecto a las direcciones. La versión anterior de este terminal (endpoint) falló con un error HTTP cuando la dirección dada era desconocida para la billetera. Esto era engañoso, ya que una dirección que es desconocida para la billetera podría seguir perteneciendo a ella. Para reflejar esto, el terminal V1 ya no falla, y en cambio cuando una dirección no es reconocida devuelve un nuevo campo isOurs, que indica que la dirección es nuestra, o que no es reconocida.
-
Una petición DELETE a /api/v1/wallets/{wallet} (DELETE = BORRAR) ahora falla correctamente con un código de respuesta HTTP 404 si la billetera no existe. Anteriormente, respondió incorrectamente con 204.
Independientemente de si se ejecuta la capa (layer) de datos antigua o la nueva, la API V1 tendrá los cambios descritos anteriormente. Los dos primeros cambios están destinados principalmente a que los desarrolladores puedan entender lo que está sucediendo. Si las centrales u otras partes lo utilizan para crear un mensaje de error específico para su API o interfaz, puede romperse.
El tercer cambio es más sutil y en realidad es una corrección de errores. El antiguo comportamiento del punto final de la dirección GET era enviar información incorrecta a los nodos, por lo que lo hemos corregido para mejorar su precisión. Al hacerlo, tuvimos que introducir un nuevo campo isOurs y revisar los estados HTTP que se estaban enviando - en caso de que las centrales hayan estado confiando en esto para cualquier lógica de negocio, tendrán que actualizarlo.
La instalación por defecto de Cardano 1.4 vendrá con la API de la cartera V1 solamente.
Generalmente, las centrales y otros integradores utilizan versiones estables para construir un cliente Cardano utilizando un script shell que lanza una cartera Cardano contra mainnet:
nix-build -A connectScripts.mainnet.wallet
En este caso no hay retroceso - la billetera Cardano se actualiza a V1.
Para tener funcionalidad V0 y V1, los desarrolladores deben usar UseLegacyDataLayer en el archivo custom-wallet-config.nix tal y como se describe en nuestra documentación para intercambios. Precaución! En este modo, a pesar de que los terminales V1 están disponibles, la API no utilizará la capa de datos recientemente desarrollada. Como consecuencia, los desarrolladores pueden experimentar limitaciones conocidas de la capa de datos heredada. Por lo tanto, este modo es obsoleto y recomendamos encarecidamente a los usuarios que ejecuten nodos sin él.
Hemos descrito los cambios incompatibles que vienen con la API de la billetera en Cardano 1.4. Si alguien tiene problemas para actualizar a la versión 1.4, busque ayuda a través de un canal de comunicación ya establecido o a través de nuestro portal de soporte.
Material gráfico, Mike Beeple