API pública

Documentación de referencia de las APIs Suivi

9 min de lectura

Lista de APIs disponibles

Esta sección describe la lista de APIs ofrecidas por Suivi. Esta lista es accesible desde la URL de su sitio ingresando swagger al final (ej.: https://domain.suivi.co/swagger).

Tenga en cuenta que la página swagger ha sido enriquecida con el esquema de cada root disponible.

API Board Mapping

La API BoardMapping permite:

  • Agregar un mapeo de board después de una importación recurrente
  • Actualizar un mapeo de tablero,
  • Eliminar un mapeo de tablero.

API Tableros

La API de Boards permite realizar acciones relacionadas con los boards tales como:

  • Actualizar los roles de los miembros especificados (usuario y/o equipo),
  • Buscar la lista de boards de un espacio de trabajo,
  • Buscar la vista de un tablero por su nombre,
  • Buscar los mapeos de importación CSV de un tablero,
  • Exportar un tablero en formato CSV,
  • Recuperar la lista de secciones de un board
  • Recuperar la lista de vistas de un board
  • Cambiar el rol de un usuario por un rol de tipo admin, contribuidor o visitante
  • Invitar usuarios a un board y asignarles un rol,
  • Importar datos CSV en un board,
  • Copiar un board,
  • Copiar un board desde un número de secuencia,
  • Cambiar el estado de compartición de una vista,
  • Conocer el estado compartido de las vistas de un tablero,
  • Modificar las variables de un tablero,
  • Encontrar la lista de variables utilizadas en un tablero,
  • Encontrar la lista de conexiones utilizadas en un board,
  • Modificar las conexiones de un board,
  • Proporcionar una vista previa de los boards vinculados que se duplicarán al duplicar un board,
  • Duplicar un board y todos sus boards vinculados,
  • Verificar los enlaces entre dos boards.

API BoardWebHook

La API BoardWebhook permite:

  • Conocer los webhooks de un board por identificador de board,
  • Conocer los webhooks de un board por identificador de webhook,
  • Agregar un webhook,
  • Eliminar un webhook,
  • Lanzar un webhook,
  • Detener un webhook.

API Book

La API Book permite:

  • Personalizar el fondo del book con una imagen proporcionada por URL o por archivo transmitido en el blob storage,
  • Personalizar los logos del book (pequeño y grande),
  • Personalizar el tema del book (claro, sólido, imagen),
  • Personalizar el color primario del book en caso de tema de tipo sólido,
  • Verificar que un usuario tiene derecho a ver un book y un elemento de book.

API Context

La API Context permite conocer el contexto relativo al usuario actual.

API Tenants

La API Tenants permite:

  • Buscar un tenant por nombre (exacto),
  • Buscar la lista de tenants accesibles por un usuario,
  • Actualizar los roles de los usuarios del tenant (Admin, Colaborador y Visitante),
  • Invitar a un usuario y asignarle un rol en un tenant,
  • Crear un nuevo tenant.

API Users

La API de Usuarios permite:

  • Buscar un usuario por nombre, apellido y dirección de correo electrónico,
  • Crear, modificar un usuario

API Workspaces

La API Workspaces permite:

  • Buscar la lista de workspaces accesibles por un usuario,
  • Modificar los roles de Administrador, Colaborador o Visitante de un usuario en un espacio de trabajo,
  • Invitar a un usuario y asignarle un rol en un espacio de trabajo,
  • Crear un nuevo workspace.

Autenticación y acceso a las API

Obtener una clave API

La conexión a las API de Suivi requiere proporcionar una clave de API asociada a una cuenta de usuario de tipo Admin del tenant.

Para encontrar esta clave, simplemente haga clic en el avatar en el tenant de trabajo y elija > Modificar mi perfil, pestaña API key.

Tenga en cuenta que es posible generar una nueva clave, pero que siempre hay una sola clave de API por tenant (la clave antigua queda desactivada).

Acceder a las API Swagger

Esta sección describe la lista de API ofrecidas por Suivi. Esta lista es accesible desde la URL de su sitio ingresando swagger al final (ej.: https://domain.suivi.co/swagger).

Tenga en cuenta que la página swagger se ha enriquecido con el esquema de cada root disponible.

Esta clave le será necesaria para conectarse a la API Swagger de Suivi tal como:

🔐 Clave de API: my-api-key Esta clave debe incluirse en el encabezado user-api-key de todas sus solicitudes.

Book (portal)

La sección Book agrupa el conjunto de endpoints que permiten personalizar la apariencia y el contenido de un book en su aplicación.

Modificación de la imagen de fondo de un book

Existen dos formas de cambiar la imagen de fondo:

  • Enviando la URL de una imagen disponible en internet
  • Cargando un archivo

Modificación por URL

Método: PUT

URL: public-api/Book/{BookId}/BackgroundImage

Parámetros:

  • El ID del book que se desea modificar que se encuentra en la URL de la solicitud
  • El JSON en el cuerpo de la solicitud que contiene la URL de la imagen

Cuerpo de la solicitud:

Ejemplo:

Modificación por carga de imagen

Método: POST

URL: public-api/Book/{BookId}/BackgroundImageUpload

Parámetros:

{  "ImageUrl": "string"}
curl -X 'PUT' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImage](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImage)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "ImageUrl": "[https://www.image.fr/mon_image.png](https://www.image.fr/mon_image.png)"}'
  • El ID del book que se desea modificar que se encuentra en la URL de la solicitud
  • La imagen en forma de archivo en el cuerpo de la solicitud

Ejemplo:

Modificación del logo de un book

Hay dos logos para cargar en este método:

curl -X 'POST' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImageUpload](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImageUpload)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: multipart/form-data' \  -F '[email protected];type=image/jpeg'
  • El logo clásico que se muestra en el book
  • El logo responsive para la visualización móvil

Método: POST

URL: public-api/Book/{BookId}/Logo

Parámetros:

  • El ID del book que se desea modificar que se encuentra en la URL de la solicitud
  • La imagen en forma de archivo en el cuerpo de la solicitud para el logo clásico
  • La imagen en forma de archivo en el cuerpo de la solicitud para el logo responsive

Ejemplo:

Modificación del tema

Existen tres tipos de tema para un book:

curl -X 'POST' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Logo](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Logo)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: multipart/form-data' \  -F '[email protected];type=image/png' \  -F '[email protected];type=image/png'
  • Light: El book tendrá una franja blanca a la izquierda con un color de los títulos al pasar el ratón
  • Dark: El book tendrá una banda del color seleccionado
  • Transparent: La banda será transparente y dejará ver la imagen de fondo

Los colores se definen en una tabla de clave-valor que puede recuperar a través del endpoint dedicado (consulte la sección "Recuperación de los colores del tema" a continuación).

Método: PUT

URL: public-api/Book/{BookId}/Theme

Parámetros:

  • El ID del book que se desea modificar que se encuentra en la URL de la solicitud
  • El tema transmitido en el cuerpo de la solicitud. Valores posibles:
    • Light
    • Dark
    • Transparent
  • El color transmitido en el cuerpo de la solicitud, en forma de un entero correspondiente al índice del color que se desea en el array de colores proporcionado por la API

Cuerpo de la solicitud:

Ejemplo:

Recuperación de los colores del tema

Recuperación de los colores disponibles para el tema de un book. La API devuelve un array de clave-valor que contiene el índice y el valor hexadecimal del color asociado.

Método: GET

URL: public-api/Book/ColorPalette

Respuesta:

Ejemplo:

Board

La sección Board agrupa los endpoints que permiten gestionar las variables y conexiones de un board.

Recuperación de las variables

Es posible recuperar todas las variables de un board.

Método: GET

URL: public-api/Boards/{BoardId}/variables

Parámetros:

{  "Theme": "string",  "ColorIndex": 0}
curl -X 'PUT' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Theme](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Theme)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "Theme": "Transparent",  "ColorIndex": 5}'
{  "0": "#000000",  "1": "#303E4D",  "2": "#667684",  "3": "#B5BCC2",  "4": "#0652A7",  "5": "#3082B7",  "...": "..."}
curl -X 'GET' \  '[https://localhost:5001/public-api/Book/ColorPalette](https://localhost:5001/public-api/Book/ColorPalette)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'
  • El ID del board que se encuentra en la URL de la solicitud

Respuesta:

Ejemplo:

Modificación de las variables

{  "Var01": "Val01",  "Var02": "NewVal02",  "Var03": "Val03"}
curl -X 'GET' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'
Importante

La lista proporcionada reemplazará las variables existentes. Se recomienda recuperar las variables primero y luego enviar la lista completa de variables que se desean.

Método: PUT

URL: public-api/Boards/{BoardId}/variables

Parámetros:

  • El ID del board que se encuentra en la URL de la solicitud
  • JSON con la lista de variables en el cuerpo de la solicitud

Cuerpo de la solicitud:

Ejemplo:

Recuperación de las conexiones

Es posible recuperar las conexiones de un board.

{  "var1": "Plop",  "var2": "65536"}
curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "var1": "Plop",  "var2": "65536"}'
Notas

La información sensible de tipo secreto para los tokens o valores de los encabezados no se muestra en la API.

La respuesta mostrada tiene en cuenta los dos tipos de conexiones existentes en la aplicación:

  • Conexión Azure DevOps
  • Conexión HTTP

Método: GET

URL: public-api/Boards/{BoardId}/connections

Parámetros:

  • El ID del tablero que se encuentra en la URL de la solicitud

Ejemplo:

Respuesta:

Modificación de una conexión

La modificación de una conexión es posible, pero requiere respetar ciertas reglas. Para ello, primero necesitamos el ID de la conexión que podemos recuperar a través de la API, y luego proporcionar un JSON correctamente configurado según lo que deseemos hacer.

curl -X 'GET' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'
{  "01JE6DY43AC7R7S2TPDAPJJ16E": {    "Id": "01JE6DY43AC7R7S2TPDAPJJ16E",    "Name": "TestFixed",    "Type": "AzureDevOps",    "Properties": {      "Organization": "statshvss",      "PersonalToken": "***"    }  },  "01JHJS7BQKH6SHMBMR7JFTNAFY": {    "Id": "01JHJS7BQKH6SHMBMR7JFTNAFY",    "Name": "TestHttp",    "Type": "Http",    "Properties": {      "BaseUrl": "[https://www.google.com](https://www.google.com)",      "Headers": [        "C",        "B"      ]    }  }}
Importante

Siempre se debe mantener el tipo en el JSON, incluso si este no va a ser modificado.

Acciones posibles:

  • Añadir un atributo
  • Modificar el valor de un atributo
  • Eliminar un atributo

Método: PUT

URL: public-api/Boards/{BoardId}/connections/{ConnectionId}

Parámetros:

  • El ID del tablero que se encuentra en la URL de la solicitud
  • El ID del conector que se encuentra en la URL de la solicitud
  • JSON en el cuerpo de la solicitud

Agregar un atributo

Esto es lo que debe contener el JSON para agregar atributos:

  • Agregar un atributo "BaseUrl" con el valor "hello"
  • Adición de un nuevo header que se llama "X-Custom-Header" con el valor "miValor"

Cuerpo de la solicitud:

Ejemplo:

Actualizar un atributo

Aquí actualizo mi atributo BaseUrl con un nuevo valor y actualizo mi header X-Custom-Header con un nuevo valor:

Cuerpo de la solicitud:

Ejemplo:

Eliminar un atributo

Aquí elimino el header X-Custom-Header:

Cuerpo de la solicitud:

Ejemplo:

{  "Type": "Http",  "BaseUrl": {    "NewValue": "hello"  },  "Headers": {    "X-Custom-Header": {      "Action": "Add",      "Value": "maValeur"    }  }}
curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "BaseUrl": {      "NewValue": "hello"    },    "Headers": {      "X-Custom-Header": {        "Action": "Add",        "Value": "maValeur"      }    }  }'
{  "Type": "Http",  "BaseUrl": {    "NewValue": "hello"  },  "Headers": {    "X-Custom-Header": {      "Action": "Update",      "Update": {        "NewValue": "Plop"      }    }  }}
curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "BaseUrl": {      "NewValue": "hello"    },    "Headers": {      "X-Custom-Header": {        "Action": "Update",        "Update": {          "NewValue": "Plop"        }      }    }  }'
{  "Type": "Http",  "Headers": {    "X-Custom-Header": {      "Action": "Remove"    }  }}
curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "Headers": {      "X-Custom-Header": {        "Action": "Remove"      }    }  }'

Artículos relacionados

¿Fue útil esta página?