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.en-gb.md
+17-17Lines changed: 17 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,21 +16,21 @@ Historically, OVHcloud APIs have been available under the **/1.0** branch corres
16
16
17
17
A new section of the OVHcloud APIs is available under the prefix **/v2** on [https://eu.api.ovh.com/v2](https://api.ovh.com/console-preview/?branch=v2){.external}.
18
18
19
-
This new branch will bring together new API routes, reworked in a new format, and become the main API branch for new feature developments in OVHcloud products.<br>
20
-
Branch**/1.0** will continue to exist in parallel to branch**/v2** but will not contain the same functionality. As a client, you can consume APIs from branch **/1.0** and **/v2** simultaneously in your programmes, while retaining the same authentication and tools to call the API. To standardise the naming of our API branches, the **/1.0** branch is also available via the **/v1** alias.
19
+
This new branch will bring together new API routes, reworked in a new format, and become the main API branch for new feature developments of OVHcloud products.<br>
20
+
The**/1.0**branch will continue to exist in parallel to the**/v2**branch but will not contain the same functionality. As a customer, you can consume APIs from branch **/1.0** and **/v2** simultaneously in your programmes, while retaining the same authentication and tools to call the API. To standardise the naming of our API branches, the **/1.0** branch is also available via the **/v1** alias.
21
21
22
-
The branch **/v2** introduces new principles of exposure and consumption (which differ from the branch **/v1**), the purpose of this guide is to present them to you.
22
+
The **/v2**branch introduces new principles of exposure and consumption (which differ from the **/v1** branch), the purpose of this guide is to introduce them.
23
23
24
24
## Principles
25
25
26
26
### Version management
27
27
28
28
The */v2* branch of the API uses a versioning system to manage its specifications. This means that each modification in the API routes (input parameters, expected return, ...) will be the subject of a new version.
29
-
These versions (which are different from the version contained in the API branch name) will contain two numbers that increment: major and minor versions. This makes it possible to distinguish minor changes from major/brittle changes in API schemes. Minor (non-brittle) changes increment the minor version while brittle changes increment the major version.
29
+
These versions (which are different from the version contained in the API branch name) will contain two numbers that increment: major and minor versions. This makes it possible to distinguish minor changes from major/breaking changes in API schemes. Minor (non-breaking) changes increment the minor version while breaking changes increment the major version.
30
30
31
31
A summary of the changes (*changelog*) accompanies the publication of each new version to get a detailed view of the changes made.
32
32
33
-
The API’s*v2* branch is designed to expose several major versions in parallel. This means that applications using a specific version of the API will continue to work after the release of a new major version.
33
+
The API *v2* branch is designed to expose several major versions in parallel. This means that applications using a specific version of the API will continue to work after the release of a new major version.
34
34
35
35
As a customer, you will be responsible for choosing the version you use. You will need to specify which major version of the specification will be used with your account.
If this header is not provided during an API call, the major version of your account is used by default.
52
52
53
53
We recommend only using this header during your validation phases. Indeed, its use in your production applications will require maintenance on your side the day that this major version is no longer available.<br>
54
-
When a major new version is released, we will evaluate the impact of this new version on your API usage, and send you a detailed report. If you are not affected by the broken changes, we will offer you to switch directly to the new major version. In this case, if you use the header in your applications, the switch cannot be performed without maintenance on your application.
54
+
When a major new version is released, we will evaluate the impact of this new version on your API usage, and send you a detailed report. If you are not affected by the breaking changes, we will offer you to switch directly to the new major version. In this case, if you use the header in your applications, the switch cannot be performed without maintenance on your application.
55
55
56
56
#### Retrieve available versions via the console
57
57
@@ -70,7 +70,7 @@ There are two opposing approaches to seeing the current state of a resource thro
70
70
71
71
The first approach is the one used by the current API: [https://eu.api.ovh.com/v1](https://eu.api.ovh.com/v1){.external}.
72
72
73
-
The APIv2 uses the resource-centric approach, which makes it easier to use *as-code*, particularly with tools like [Terraform](https://www.terraform.io){.external}. This operation also abstracts all the complexity of the process of transforming a resource from one state to another since it is the responsibility of the API and not the client.
73
+
The APIv2 uses the resource-centric approach, which makes it easier to use *as-code*, particularly with tools like [Terraform](https://www.terraform.io){.external}. This operation also abstracts all the complexity of the process of transforming a resource from one state to another since it is the responsibility of the API and not the customer.
74
74
75
75
### Asynchronous management and events
76
76
@@ -117,20 +117,20 @@ In some cases, an event may also contain a link to the resource that the task is
117
117
118
118
> [!primary]
119
119
>
120
-
> The event and task examples shown above may vary by API section. Please refer to the [console](https://help.ovhcloud.com/csm/en-gb-api-console-exploration?id=kb_article_view&sysparm_article=KB0057325) to view the exact definition for each section.
120
+
> The event and task examples shown above may vary by API section. Please refer to the [console](pages/account/api/console-preview/) to view the exact definition for each section.
121
121
>
122
122
123
123
### Pagination
124
124
125
-
Paging allows you to segment API responses containing a list of items into multiple pages.
125
+
Pagination allows you to segment API responses containing a list of items into multiple pages.
126
126
127
127
The main advantages of pagination are:
128
128
129
-
- Reduced bandwidth usage for API clients
130
-
-shorter API response times
131
-
-smaller response bodies, which allows for less expensive exploitation of the data returned from the client side.
129
+
- Reduced bandwidth usage for API clients.
130
+
-Shorter API response times.
131
+
-Smaller response bodies, which allows for less expensive exploitation of the data returned from the client side.
132
132
133
-
The APIv2 exposes cursor paging, in which cursors are passed in the query and response headers. You can also control the number of returned items.
133
+
The APIv2 exposes cursor pagination, in which cursors are passed in the query and response headers. You can also control the number of returned items.
The absence of the `X-Pagination-Cursor-Next` header in an API response containing a list of items means that the last page is reached and all available items have been returned.
156
156
157
-
## Official customers
157
+
## Official clients
158
158
159
159
Several libraries are available to use the OVHcloud APIs:
160
160
@@ -164,8 +164,8 @@ Several libraries are available to use the OVHcloud APIs:
0 commit comments