You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/account/api/apiv2/guide.fr-fr.md
+46-28Lines changed: 46 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,54 +1,57 @@
1
1
---
2
-
title: APIv2
3
-
slug: ovh-api-v2
4
-
excerpt: First Steps with the OVHcloud API v2
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
5
section: APIv6 OVHcloud
6
-
updated: 2023-03-20
6
+
updated: 2023-04-17
7
7
---
8
8
9
-
**Dernière mise à jour le 20/03/2023**
9
+
**Dernière mise à jour le 17/04/2023**
10
10
11
11
## Objectif
12
12
13
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
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é.
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
16
17
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
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. 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**.
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**.
20
21
21
-
La branche **/v2** introduit des nouveaux principes d'exposition et de consommation (qui diffèrent de la branche **/v1**), et ce guide a pour vocation de vous les présenter.
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.
22
23
23
24
## Principes
24
25
25
26
### Gestion des versions
26
27
27
-
La branche */v2* de l'API utilise un système de versionnement pour la gestion de ses spécifications: c'est à dire que chaque modification dans les routes d'API (paramètres d'entrées, retour attendus, ...) feront l'objet d'une nouvelle version.
28
-
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.
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.
29
30
30
-
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.
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.
31
32
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.
33
34
34
-
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.
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.
35
36
36
-
Au moment de la publication d'une nouvelle version majeure, la version majeure précédent celle-ci restera active pendant une période définie dans le *CHANGELOG* afin de vous laisser le temps d'adapter vos applications.
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.
37
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.
38
39
39
40
#### Sélectionner une version majeure spécifique de l'API
40
41
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.
42
43
43
-
Vous aurez probablement le besoin de tester vos applications avec la nouvelle version majeure avant de faire le changement dans votre espace client.
44
-
Pour cela, vous pouvez indiquer la version majeure à utiliser avec l'en-tête `X-Schemas-Version` dans vos appels API:
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
+
45
47
```bash
46
48
curl -X GET -H "X-Schemas-Version: 1.0" https://eu.api.ovh.com/v2/iam/policy
47
49
```
48
50
49
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.
50
52
51
-
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écessiteront une maintenance de votre côté le jour où cette version majeure ne sera plus disponible. 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, et vous enverrons un rapport détaillé. Si vous n'êtes pas impacté 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.
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.
52
55
53
56
#### Récupérer les versions disponibles via la console
54
57
@@ -61,20 +64,22 @@ Les différentes versions sont affichées dans la section **SCHEMAS VERSION**. V
61
64
### Vision as-code
62
65
63
66
Deux approches opposées existent pour voir l'état courant d'une ressource à travers une API et changer son état :
64
-
-*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).
65
-
-*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é.
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é.
66
70
67
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}.
68
72
69
-
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.
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.
70
74
71
75
### Gestion asynchrone et évènements
72
76
73
-
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. Ces actions peuvent dans certains cas entraîner des tâches de longue durée, dont la résolution se fera de manière asynchrone.
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.
74
78
75
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.
76
80
77
81
Voici un exemple de tâche retournée par l'API :
82
+
78
83
```json
79
84
{
80
85
"createdAt": "2023-03-21T15:40:05.213Z",
@@ -97,6 +102,7 @@ Voici un exemple de tâche retournée par l'API :
97
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`.
98
103
99
104
Voici un exemple d'évènement retourné par l'API :
105
+
100
106
```json
101
107
{
102
108
"createdAt": "2023-03-21T15:50:08.823Z",
@@ -119,35 +125,47 @@ Dans certains cas, un évènement peut aussi contenir un lien vers la ressource
119
125
La pagination permet de segmenter les réponses d'API contenant une liste d'éléments en plusieurs pages.
120
126
121
127
Les avantages principaux de la pagination sont :
122
-
- réduction de l'utilisation de la bande passante pour les clients de l'API
123
-
- temps de réponse de l'API plus courts
124
-
- 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
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.
125
132
126
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.
127
134
128
135
Les en-têtes utilisés sont les suivants :
129
-
-`X-Pagination-Size` : cet en-tête optionnel permet de contrôler la taille des pages retournées
130
-
-`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
131
-
-`X-Pagination-Cursor` : en-tête à envoyer dans une requête pour récupérer la page suivante
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.
132
140
133
141
Par exemple, l'appel suivant retournera les 5 premiers éléments ainsi que le curseur à utiliser pour récupérer la page suivante :
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.
146
156
147
-
148
157
## Clients officiels
149
158
150
159
Plusieurs bibliothèques sont disponibles pour utiliser les API OVHcloud :
160
+
151
161
- Go : [https://github.com/ovh/go-ovh](https://github.com/ovh/go-ovh){.external}
0 commit comments