API GraphQL
Les données de Coutosuix peuvent être requêtées en utilisant le protocol GraphQL.
Pour activer l'accès GraphQL à votre instance, merci de nous contacter.
Acces depuis une interface Web
Une interface web est disponible à l'adresse :
https://moninstance.coutosuix.fr/graphql/Si vous êtes connecté à Coutosuix vous aurez accès aux données mises à disposition à l'utilisateur connecté. Sinon vous pouvez utiliser le jeton d'API ci-dessous.
Authentification
L'authentification à l'API doit se faire à l'aide d'un jeton d'API. Celui-ci doit être généré depuis l'interface dans Administration / Jeton d'API
Ensuite ce jeton doit être transmis à chaque requête GraphQL dans l'en-tête HTTP "Authorization"
Exemple d'utilisation avec cURL:
curl -H "Authorization: a1367b53-45b2-4138-be95-b5c174463174" -H "Content-Type: application/json" -d '{"query": "{ projects {id}}"}' https://moninstance.coutosuix.fr/graphql/
Exemples de requêtes
Récupérer tous les projets et leurs tâches
query {
projects {
name
shortname
tasks {
name
shortname
}
}
}Récupérer les heures passées mises à jour depuis une date
{
workedHours(
filters: {updatedAt: {gt: "2024-03-15"}}
) {
user {
id
}
recoverableQuantity
quantity
date
updatedAt
}
}
Pagination
L'API utilise une pagination par limit / offset. Par défault la limite est fixée à 1000. Il s'agit aussi d'un maximum possible.
Cela veut dire qu'il ne sera pas possible de récupérer plus de 1000 élément avec une seule requête. Il faudra refaire une requête est définissant offet.
Exemple
{
workedHours(
order: {updatedAt: DESC}
pagination: {limit: 100, offset: 100}
) {
user {
id
}
recoverableQuantity
quantity
date
}
}
Modifications
Il est possible de pousser des modifications dns coutosuix avec des Mutations GraphQL.
Projets / Tâches - createProject, updateProject, deleteProject
Ajouter, modifier ou supprimer un projet ou une tache
mutation {
createProject(data: {name: "Super projet", shortname: "X22R"}) {
... on ProjectType {
id
name
}
}
}Cette méthode créé le projet avec les informations données, et renvoi les informations du projet créé indiquées.
Pour update et delete, le fonctionnement est similaire mais il faut impérativement préciser "id" afin d'identifier le projet ou la tâche.
En cas d'erreur de validation, par défaut, aucun problème n'est remonté. Pour cela il faut demander à récupérer le type "OperationalInfo"
mutation {
createProject(data: {name: "Super projet", shortname: "X22R"}) {
... on ProjectType {
id
name
}
... on OperationInfo {
__typename
messages {
code
field
kind
message
}
}
}
}Exemple d'erreur renvoyée :
{
"data": {
"createProject": {
"__typename": "OperationInfo",
"messages": [
{
"code": "unique",
"field": "shortname",
"kind": "VALIDATION",
"message": "Un objet Projet avec ce champ Nom court existe déjà."
}
]
}
}
}Projet / Tâche - updateOrCreateProject / updateOrCreateTask
Une méthode "update or create" existe pour les projets et tâches. Elle permet en une seule requête de crérer ou bien de mettre à jour l'objet selon s'il existe déjà en base ou pas.
mutation {
updateOrCreateProject(
select: {id: "42"}
data: {name: "Super !"}
) {
... on ProjectType {
id
name
}
}
}Dans "select" on indique les champ servant à identifier le projet ou la tâche (il faut que la sélection corresponde à un élément unique)
Puis les données "data" sont celles qui seront mises a jour. Si l'objet identifié par "select" n'existe pas, il sera créé avec les données de "select" et de "data".
Identifiant externe à Coutosuix
Il est possible de stocker un identifiant externe à Coutosuix. Pour cela il faut utiliser le champ "externalId" (qui doit être unique).
Il peut donc servir de sélecteur pour la méthode updateOrCreate.
Contingent / Estimated daily quota - updateOrCreate
Met à jour ou créé une journée d'un contingent d'un utilisateur.
mutation {
estimatedDailyQuota {
updateOrCreate(
data: {userId: 10, quantity: 420, leave: FULL, date: "2024-01-01"}
) {
... on EstimatedDailyQuotaType {
id
user {
id
}
}
}
}
}Cette méthode renvoie l'objet créé ou modifié avec les champs voulus.
Contingent / Estimated daily quota - updateOrCreateBulk
Met à jour ou créé en ensemble de journées de contingent
mutation {
estimatedDailyQuota {
updateOrCreateBulk(data: [
{userId: 10, date: "2024-01-01", quantity: 420, leave: NO},
{userId: 11, date: "2024-01-01", quantity: 450, leave: HALF},
]) {
... on EstimatedDailyQuotaResultCountType {
count
}
}
}
}L'API renverra le nombre d'éléments créés ou mis à jour :
{
"data": {
"estimatedDailyQuota": {
"updateOrCreateBulk": {
"count": 2
}
}
}
}Définir l'état de validation de l'année
Pour cela il est possible d'ajouter le paramètre yearValidationState: VALIDATED aux données.
Cela va mettre à jour l'état avec celui indiqué pour l'utilisateur et l'année.
Dans le cas d'une mise à jour multiple (bulk update), le dernier état de chaque utilisateur année sera prit en compte.
Exemple:
estimatedDailyQuota {
updateOrCreateBulk(
data: [
{userId: 10, date: "2024-01-01", quantity: 10, leave: NO, yearValidationState: VALIDATED},
{userId: 10, date: "2024-05-01", quantity: 20, leave: FULL, yearValidationState: DRAFT}
]
) {
... on EstimatedDailyQuotaResultCountType {
count
}
}
}
Utilisateur 10, année 2024 l'état sera modifié à DRAFT