API REST¶

L'API REST v2 de YULPA permet de piloter votre compte depuis vos propres outils : scripts, tableaux de bord, logiciel de gestion, intégration continue… Elle donne accès aux mêmes données et aux mêmes actions que le manager iWal : services, factures, zones DNS, bases MySQL, messagerie, tickets de support, renouvellements, etc.

Cette section s'adresse à un public technique (développeurs, administrateurs système).

Pages de cette section¶

Jetons d'accès : créer un jeton, choisir ses périmètres, le révoquer, et les bonnes pratiques de sécurité.
Exemples : exemples d'appels avec curl, PHP et Python pour les opérations les plus courantes.

URL de base¶

Toutes les routes de l'API sont servies sous :

https://my.yulpa.io/api/v2

Par exemple, la liste de vos services se trouve à l'adresse https://my.yulpa.io/api/v2/services.

Authentification¶

Chaque appel s'authentifie avec un jeton d'accès personnel, envoyé dans l'en-tête Authorization :

curl -H "Authorization: Bearer iwal_xxxxxxxx" https://my.yulpa.io/api/v2/me

Un jeton commence toujours par iwal_. Il se crée depuis votre session du manager iWal : voir Jetons d'accès.

Note

Le jeton est soumis aux mêmes règles que la connexion au manager : le pare-feu de votre compte doit autoriser la connexion depuis l'adresse IP qui appelle l'API, et un compte désactivé invalide ses jetons.

Droits¶

Un jeton agit avec les droits de l'utilisateur qui l'a créé, exactement comme dans le manager :

vous voyez les clients et services dont vous êtes titulaire, ainsi que ceux sur lesquels une délégation vous a été accordée ;
les rôles de la délégation s'appliquent (par exemple, la facturation demande un rôle permettant de voir les factures, la gestion technique d'un hébergement un rôle technique).

Les périmètres d'un jeton (par exemple services:read) ne donnent aucun droit supplémentaire : ils restreignent ce que le jeton peut faire. Voir Jetons d'accès.

Quand une ressource n'existe pas, ou que vous n'avez aucun droit dessus, l'API répond 404 (elle ne révèle pas l'existence d'une ressource qui ne vous concerne pas). Si vous avez un droit sur la ressource mais pas le bon rôle, ou si le jeton n'a pas le périmètre nécessaire, la réponse est 403.

Format des requêtes et des réponses¶

Les corps de requête sont en JSON (Content-Type: application/json).
Les noms de champs sont en anglais, en snake_case (client_id, expires_at…).
Les dates sont au format AAAA-MM-JJ HH:MM:SS, à l'heure de Paris.

Succès¶

Une réponse réussie contient la ressource dans data, et des informations complémentaires dans meta :

{
  "data": {
    "id": 12345,
    "name": "Hébergement exemple.fr",
    "status": { "code": 30, "label": "OK", "detail": null }
  },
  "meta": {}
}

Code	Signification
`200`	Succès
`201`	Ressource créée (renvoyée dans `data`)
`202`	Demande acceptée, traitée ensuite par nos serveurs (par exemple la régénération d'une zone DNS)
`204`	Succès sans contenu (suppression, révocation)

Erreurs¶

Les erreurs sont renvoyées au format application/problem+json (RFC 9457) :

{
  "type": "about:blank",
  "title": "Requête invalide",
  "status": 400,
  "detail": "Paramètres invalides",
  "errors": {
    "name": "Nom obligatoire, 100 caractères maximum"
  }
}

Le champ errors détaille, champ par champ, les erreurs de validation.

Code	Signification
`400`	Requête invalide (paramètre manquant ou incorrect)
`401`	Non authentifié : jeton absent, invalide, expiré ou révoqué, ou adresse IP refusée par le pare-feu du compte
`403`	Accès refusé : rôle insuffisant, périmètre absent du jeton, ou opération réservée au manager
`404`	Ressource introuvable (ou aucun droit dessus)
`409`	Conflit avec l'état de la ressource (par exemple : service déjà dans une commande en cours)
`500`	Erreur interne : nos équipes sont prévenues automatiquement

Pagination¶

Les listes sont paginées avec les paramètres page (à partir de 1) et per_page (50 par défaut, 100 au maximum) :

curl -H "Authorization: Bearer iwal_xxxxxxxx" \
  "https://my.yulpa.io/api/v2/services?page=2&per_page=100"

La réponse indique dans meta la page courante, le nombre d'éléments par page, le nombre total d'éléments et le nombre de pages :

"meta": { "page": 2, "per_page": 100, "total": 214, "total_pages": 3 }

Limites¶

per_page : 100 éléments au maximum par page.
Vérification de disponibilité d'un nom de domaine (GET /v2/domains/check) : 60 vérifications par utilisateur toutes les 10 minutes, car chaque vérification interroge le registrar.
Commande : 50 éléments au maximum par commande ; un service ne peut figurer que dans une seule commande en cours à la fois.

Attention

Les appels sont réels : une suppression ou une commande passée par l'API a le même effet que depuis le manager.

Ce qui reste réservé au manager¶

Certaines opérations sensibles ne sont pas possibles avec un jeton. Elles se font uniquement depuis votre session du manager iWal (l'API répond 403 si vous les appelez avec un jeton) :

la création et la révocation des jetons d'accès (un jeton ne peut pas créer d'autre jeton) ;
la sécurité du compte : mot de passe, téléphone, pare-feu, double authentification, après déverrouillage ;
l'ajout et le retrait de clés SSH (la liste des clés reste lisible avec un jeton) ;
la déconnexion (un jeton se révoque, il ne se déconnecte pas).

Documentation interactive et contrat OpenAPI¶

La référence complète de l'API (toutes les routes, leurs paramètres et leurs réponses) est disponible :

en documentation interactive (Swagger UI) : https://my.yulpa.io/api/v2/docs ;
sous forme de contrat OpenAPI 3.1 : https://my.yulpa.io/api/v2/openapi.yaml, à importer dans votre outil préféré (Postman, Insomnia, générateur de client…).

Dans la documentation interactive, le bouton Try it out d'une route permet de l'essayer :

si vous êtes connecté au manager iWal dans le même navigateur, les appels utilisent votre session ;
sinon, cliquez sur Authorize et collez un jeton dans le champ bearer (il n'est conservé que le temps de la page).

Danger

Les appels faits depuis la documentation interactive agissent sur vos vraies données.