Requisitos previos
Tu suscripción a Digiforma debe incluir la opción API GraphQL. Dirígete a la pestaña de opciones avanzadas para comprobar si lo tienes.
Presentación de la API GraphQL
GraphQL es un lenguaje moderno de solicitud API concebido para mejorar la forma en la que las aplicaciones recuperan y manipulan los datos desde un servidor.
La API GraphQL de Digiforma ofrece acceso a un gran modelo de datos en lectura y escritura. Es la solución ideal para desarrollar conexiones muy sofisticadas.
Principios clave:
Solicitudes precisas: GraphQL te permite preguntar exactamente lo que quieres, ni más ni menos, reduciendo así la cantidad de datos intercambiados.
Una sola petición, varios recursos: puedes recuperar varias fuentes vinculadas a una sola solicitud, reduciendo el número de peticiones necesarias del servidor.
Estructura clara: los datos devueltos corresponden a una estructura definida dentro de tu solicitud, facilitando así la integración en tus aplicaciones.
Ejemplo simple:
Esta solicitud devuelve exactamente el ID, nombre y correo electrónico del candidato con el identificador 123.
Ventajas de GraphQL
Puedes descubrir y probar GraphQL directamente en tu cuenta gracias a una interfaz web interactiva: GraphiQL.
Puedes probar tus solicitudes y explorar el esquema GraphQL antes de desarrollar tu propio conector y código fuera de Digiforma.
Para utilizar GraphiQL, necesitarás configurar la autenticación de acuerdo con el proceso descrito a continuación.
En GraphiQL el encabezado de autenticación se configura aquí:
Atención, esta interfaz manipula los datos de producción de tu cuenta.
Conexión a la API
Endpoint
La API GraphQL de Digiforma es accesible a través de este Endpoint:
https://app.digiforma.com/api/v1/graphql
Autenticación
Generación de un token
El método de autenticación utiliza un token Bearer en el encabezado HTTP.
Conéctate a tu cuenta Digiforma
Dirígete a la pestaña de configuración API
Haz clic en "generar un token"
Copia el token generado
Uso del token
El encabezado HTTP se denomina Autorization, y su valor es Bearer VOTRE_TOKEN_API
Ejemplo de línea de comandos (recuperación de todos los alumnos de la base de datos de tu cuenta):
curl -X POST
https://app.digiforma.com/api/v1/graphql
-H "Authorization: Bearer VOTRE_TOKEN_API"
-H "Content-Type: application/json"
-d '{
"query": "{ trainees { id firstname lastname } }"
}'
Conocimiento del modelo de datos
El esquema que incluye todas las estructuras de datos y funciones accesibles es explorable:
directamente en GraphiQL en tu cuenta
desde esta página pública: documentación del esquema
Ejemplos de uso
Puedes probar estos ejemplos en la interfaz GraphiQL.
Recuperar la lista de alumnos
query GetTrainees {
trainees {
id
firstname
lastname
email
phone
}
}
Recuperar un alumno específico con todos sus cursos
Sustituir ID_D_UN_APPRENANT por un verdadero ID de alumno.
query GetTrainee {
trainee(id: ID_D_UN_APPRENANT) {
id
firstname
lastname
email
phone
company {
id
name
}
training_sessions {
id
name
start_date
end_date
}
}
}
Ejemplo en phyton
Este es un ejemplo completo que recupera la lista de alumnos de la cuenta.
Remplazar YOUR_TOKEN en el código.
import requests
query = """
query GetTrainees {
trainees {
id
firstname
lastname
}
}
"""
response = requests.post(
'https://app.digiforma.com/api/v1/graphql',
json={'query': query},
headers={
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
}
)
data = response.json()
print(data)
Buenas prácticas
Optimización de solicitudes
Pregunta únicamente los campos necesarios
Utiliza la paginación para las listas grandes
Evita las solicitudes muy profundas
Gestión de errores
Comprueba siempre el campo "errores" en la respuesta
Implementa una lógica de retry apropiada
Registra los errores para desbloquear
Seguridad
Almacena tus tokens de forma segura
Genera regularmente tus tokens
Nunca enseñes tus tokens del lado de los clientes
Rendimiento
Utiliza la paginación para evitar los timeouts
Pon en incógnito las solicitudes que no cambian mucho
Evita las solicitudes N+1 utilizando las relaciones GraphQL