|
| 1 | +--- |
| 2 | +title: "API v2 OVHcloud - Principes de fonctionnement" |
| 3 | +slug: api-v2 |
| 4 | +excerpt: "Découvrez les nouveaux principes d'exposition et de consommation liés à l'API v2 OVHcloud" |
| 5 | +section: APIv6 OVHcloud |
| 6 | +updated: 2023-04-17 |
| 7 | +--- |
| 8 | + |
| 9 | +**Dernière mise à jour le 17/04/2023** |
| 10 | + |
| 11 | +## Objectif |
| 12 | + |
| 13 | +Les API disponibles sur [https://eu.api.ovh.com/](https://eu.api.ovh.com/){.external} vous permettent d'acheter, gérer, mettre à jour et configurer des produits OVHcloud sans utiliser une interface graphique comme l'espace client. |
| 14 | + |
| 15 | +Historiquement, les API d'OVHcloud sont disponibles sous la branche **/1.0** correspondant à la première version de l'API que nous avons publiée. |
| 16 | + |
| 17 | +Une nouvelle branche des API OVHcloud est disponible sous le préfixe **/v2** sur [https://eu.api.ovh.com/v2](https://api.ovh.com/console-preview/?branch=v2){.external}. |
| 18 | + |
| 19 | +Cette nouvelle branche regroupera des nouvelles routes d'API, retravaillées sous un nouveau format, et deviendra la branche d'API principale pour les nouveaux développements de fonctionnalités de produits OVHcloud.<br> |
| 20 | +La branche **/1.0** continuera d'exister en parallèle de la branche **/v2** mais ne contiendra pas la même fonctionnalité. En tant que client, vous pourrez consommer des API de la branche **/1.0** et **/v2** simultanément dans vos programmes, tout en conservant la même authentification et les mêmes outils pour appeler l'API. Afin de standardiser le nommage de nos branches d'API, la branche **/1.0** est également disponible à travers l'alias **/v1**. |
| 21 | + |
| 22 | +La branche **/v2** introduit des nouveaux principes d'exposition et de consommation (qui diffèrent de la branche **/v1**), ce guide a pour vocation de vous les présenter. |
| 23 | + |
| 24 | +## Principes |
| 25 | + |
| 26 | +### Gestion des versions |
| 27 | + |
| 28 | +La branche */v2* de l'API utilise un système de versionnement pour la gestion de ses spécifications. Cela signifie que chaque modification dans les routes d'API (paramètres d'entrées, retour attendus, ...) fera l'objet d'une nouvelle version. |
| 29 | +Ces versions (qui sont différentes de la version contenue dans le nom de branche de l'API) contiendront deux numéros qui s'incrémentent: la version majeure et la version mineure. Cela permet de distinguer les changements mineurs des changements majeurs/cassants dans les schémas de l'API. Les changements mineurs (non-cassants) incrémentent la version mineure tandis que les changements cassants incrémentent la version majeure. |
| 30 | + |
| 31 | +Un résumé des changements (*changelog*) accompagne la publication de chaque nouvelle version afin d'avoir une vue détaillée des modifications apportées. |
| 32 | + |
| 33 | +La branche *v2* de l'API est conçue pour pouvoir exposer plusieurs versions majeures en parallèle. Cela signifie que des applications utilisant une version spécifique de l'API continueront de fonctionner après la sortie d'une nouvelle version majeure. |
| 34 | + |
| 35 | +En tant que client, vous aurez la responsabilité de choisir la version que vous utiliserez. Vous devrez indiquer quelle version majeure de la spécification sera utilisée avec votre compte. |
| 36 | + |
| 37 | +Au moment de la publication d'une nouvelle version majeure, la version majeure précédente restera active pendant une période définie dans le *changelog* afin de vous laisser le temps d'adapter vos applications. |
| 38 | +Avant la fin de la période de disponibilité de la version majeure précédente, vous devrez vous assurer que vos applications utilisant l'API OVHcloud sont toujours compatibles, et faire le changement de version majeure dans votre espace client. Si vous ne le faites pas, vous serez migré automatiquement sur la dernière version majeure à la fin de la période de disponibilité de votre version majeure courante. |
| 39 | + |
| 40 | +#### Sélectionner une version majeure spécifique de l'API |
| 41 | + |
| 42 | +Une page spécifique sera prochainement disponible dans l'espace client OVHcloud pour sélectionner la version majeure de l'API utilisée. |
| 43 | + |
| 44 | +Vous aurez probablement besoin de tester vos applications avec la nouvelle version majeure avant de faire le changement dans votre espace client. |
| 45 | +Pour cela, vous pouvez indiquer la version majeure à utiliser avec l'en-tête `X-Schemas-Version` dans vos appels API : |
| 46 | + |
| 47 | +```bash |
| 48 | +curl -X GET -H "X-Schemas-Version: 1.0" https://eu.api.ovh.com/v2/iam/policy |
| 49 | +``` |
| 50 | + |
| 51 | +Si cet en-tête n'est pas fourni lors d'un appel à l'API, la version majeure de votre compte est utilisée par défaut. |
| 52 | + |
| 53 | +Nous conseillons de n'utiliser cet en-tête que lors de vos phases de validation. En effet, son utilisation dans vos applications en production nécessitera une maintenance de votre côté le jour où cette version majeure ne sera plus disponible.<br> |
| 54 | +Lors de la sortie d'une nouvelle version majeure, nous ferons une évaluation de l'impact de cette nouvelle version sur votre utilisation de l'API, un rapport détaillé vous sera envoyé. Si vous n'êtes pas concerné par les changements cassants, nous vous proposerons de basculer directement sur la nouvelle version majeure. Dans ce cas, si vous utilisez l'en-tête dans vos applications, la bascule ne pourra être effectuée sans maintenance sur votre application. |
| 55 | + |
| 56 | +#### Récupérer les versions disponibles via la console |
| 57 | + |
| 58 | +Il est possible de voir la liste des versions disponible sur la console de l'API OVHcloud. Pour cela, ouvrez la [console](https://api.ovh.com/console-preview/?section=%2Fiam&branch=v2#servers){.external}. |
| 59 | + |
| 60 | +Les différentes versions sont affichées dans la section **SCHEMAS VERSION**. Vous pouvez ensuite sélectionner une version pour voir les schémas d'API associés. |
| 61 | + |
| 62 | +{.thumbnail} |
| 63 | + |
| 64 | +### Vision as-code |
| 65 | + |
| 66 | +Deux approches opposées existent pour voir l'état courant d'une ressource à travers une API et changer son état : |
| 67 | + |
| 68 | +- **Approche centrée sur le processus** : l'API expose l'état courant des ressources (par exemple une instance Public Cloud) et offre des opérations pour les modifier (par exemple, changer la taille d'un disque). |
| 69 | +- **Approche centrée sur les ressources** : l'API expose à la fois l'état courant des ressources ainsi que l'état souhaité. Les modifications se font directement en mettant à jour l'état souhaité des ressources. Dans ce cas, l'API effectue elle-même les actions nécessaires pour atteindre l'état ciblé. |
| 70 | + |
| 71 | +La première approche est celle utilisée par l'API actuelle : [https://eu.api.ovh.com/v1](https://eu.api.ovh.com/v1){.external}. |
| 72 | + |
| 73 | +L'APIv2 utilise l'approche centrée sur les ressources, qui la rend plus facilement utilisable « *as-code* », notamment à travers des outils tels que [Terraform](https://www.terraform.io){.external}. Ce fonctionnement permet également d'abstraire toute la complexité du processus de transformation d'une ressource d'un état à un autre puisqu'il est à la charge de l'API et non du client. |
| 74 | + |
| 75 | +### Gestion asynchrone et évènements |
| 76 | + |
| 77 | +Comme expliqué dans la section précédente, l'APIv2 prend en charge les actions à effectuer pour atteindre l'état cible d'une ressource lorsque ses spécifications ont été modifiées. Dans certains cas, ces actions peuvent entraîner des tâches de longue durée, dont la résolution se fera de manière asynchrone. |
| 78 | + |
| 79 | +Dans le cas de ressources pour lesquelles des tâches asynchrones peuvent être exécutées, une route `/task` est exposée pour récupérer la liste des tâches liées à une ressource. La liste des tâches en cours est également disponible dans les informations de la ressource elle-même. |
| 80 | + |
| 81 | +Voici un exemple de tâche retournée par l'API : |
| 82 | + |
| 83 | +```json |
| 84 | +{ |
| 85 | + "createdAt": "2023-03-21T15:40:05.213Z", |
| 86 | + "startedAt": "2023-03-21T15:41:05.213Z", |
| 87 | + "updatedAt": "2023-03-21T15:42:05.213Z", |
| 88 | + "finishedAt": "2023-03-21T15:43:05.213Z", |
| 89 | + "errors": [], |
| 90 | + "id": "18704d69-7fd0-4000-808f-7e3d8bb42380", |
| 91 | + "progress": [ |
| 92 | + { |
| 93 | + "name": "Restart", |
| 94 | + "status": "DONE" |
| 95 | + } |
| 96 | + ], |
| 97 | + "status": "DONE", |
| 98 | + "type": "CloudRestartInstance" |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +Une liste d'évènements est également exposée pour les ressources concernées par des tâches asynchrones. Cela permet de dresser un historique des évènements affectant la ressource comme, par exemple, les modifications demandées par les utilisateurs, les opérations asynchrones, ou bien les maintenances effectuées sur la ressource. Ces évènements sont listés via le chemin `/event`. |
| 103 | + |
| 104 | +Voici un exemple d'évènement retourné par l'API : |
| 105 | + |
| 106 | +```json |
| 107 | +{ |
| 108 | + "createdAt": "2023-03-21T15:50:08.823Z", |
| 109 | + "message": "Task 18704d69-7fd0-4000-808f-7e3d8bb42380 started", |
| 110 | + "type": "TaskStart" |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +Le type de l'évènement peut par exemple être `TargetSpecUpdate` en cas de changement de l'état cible d'une ressource, `TaskSuccess` en cas de tâche terminée sans erreur, etc. |
| 115 | + |
| 116 | +Dans certains cas, un évènement peut aussi contenir un lien vers la ressource concernée par la tâche ainsi qu'un message. |
| 117 | + |
| 118 | +> [!primary] |
| 119 | +> |
| 120 | +> Les exemples d'évènement et de tâche présentés ci-dessus peuvent varier selon la section d'API. Veuillez vous référer à la [console](https://docs.ovh.com/fr/api/api-console-exploration/) pour visualiser la définition exacte relative à chaque section. |
| 121 | +> |
| 122 | +
|
| 123 | +### Pagination |
| 124 | + |
| 125 | +La pagination permet de segmenter les réponses d'API contenant une liste d'éléments en plusieurs pages. |
| 126 | + |
| 127 | +Les avantages principaux de la pagination sont : |
| 128 | + |
| 129 | +- une réduction de l'utilisation de la bande passante pour les clients de l'API ; |
| 130 | +- des temps de réponse de l'API plus courts ; |
| 131 | +- des corps de réponse moins volumineux, ce qui permet une exploitation moins coûteuse des données retournées du côté du client. |
| 132 | + |
| 133 | +L'APIv2 expose une pagination par curseur, dans laquelle les curseurs sont transmis dans les en-têtes des requêtes et des réponses. Il est également possible de contrôler le nombre d'éléments retournés. |
| 134 | + |
| 135 | +Les en-têtes utilisés sont les suivants : |
| 136 | + |
| 137 | +- `X-Pagination-Size` : cet en-tête optionnel permet de contrôler la taille des pages retournées ; |
| 138 | +- `X-Pagination-Cursor-Next` : en-tête retourné par l'API qui contient la valeur à utiliser dans la prochaine requête pour récupérer la page suivante ; |
| 139 | +- `X-Pagination-Cursor` : en-tête à envoyer dans une requête pour récupérer la page suivante. |
| 140 | + |
| 141 | +Par exemple, l'appel suivant retournera les 5 premiers éléments ainsi que le curseur à utiliser pour récupérer la page suivante : |
| 142 | + |
| 143 | +```bash |
| 144 | +curl https://eu.api.ovh.com/v2/iam/policy -H "X-Pagination-Size: 5" |
| 145 | +# Si le nombre de ressources à retourner est supérieur à 5, l'en-tête suivant |
| 146 | +# sera disponible dans la réponse : "X-Pagination-Cursor-Next: xxxyyyzzz" |
| 147 | +``` |
| 148 | + |
| 149 | +La page suivante peut être récupérée en fournissant le curseur renvoyé dans la réponse de l'appel précédent : |
| 150 | + |
| 151 | +```bash |
| 152 | +curl https://eu.api.ovh.com/v2/iam/policy -H "X-Pagination-Size: 5" -H "X-Pagination-Cursor: xxxyyyzzz" |
| 153 | +``` |
| 154 | + |
| 155 | +L'absence de l'en-tête `X-Pagination-Cursor-Next` dans une réponse d'API contenant une liste d'éléments signifie que la dernière page est atteinte et que tous les éléments disponibles on été retournés. |
| 156 | + |
| 157 | +## Clients officiels |
| 158 | + |
| 159 | +Plusieurs bibliothèques sont disponibles pour utiliser les API OVHcloud : |
| 160 | + |
| 161 | +- Go : [https://github.com/ovh/go-ovh](https://github.com/ovh/go-ovh){.external} |
| 162 | +- Python : [https://github.com/ovh/python-ovh](https://github.com/ovh/python-ovh){.external} |
| 163 | +- PHP : [https://github.com/ovh/php-ovh](https://github.com/ovh/php-ovh){.external} |
| 164 | + |
| 165 | +## Aller plus loin <a name="gofurther"></a> |
| 166 | + |
| 167 | +[Exploration des API OVHcloud](https://docs.ovh.com/fr/api/api-console-exploration/) |
| 168 | + |
| 169 | +[Using Terraform with OVHcloud](https://docs.ovh.com/fr/api/terraform-at-ovhcloud/) (guide en anglais) |
| 170 | + |
| 171 | +Échangez avec notre communauté d'utilisateurs sur [https://community.ovh.com](https://community.ovh.com). |
0 commit comments