API versioning allows existing automations to continue to function as the platform and the software of a product continue to grow in support of new features. With API versioning, new features or perhaps bug fixes may only be available while using the latest API version in your REST API calls.
For AOS-CX, we've named our API versioning based on the major firmware release that version was introduced. To get the latest supported API version and all supported versions an AOS-CX platform supports, execute a GET API call to the switch's /rest resource as follows:
curl -i -k -X GET "https://10.10.223.180/rest" -H "accept: */*" -d ""
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 09 Aug 2021 17:51:06 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 207
Connection: keep-alive
Etag: 1cd846e634a614607129b4157510af73
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'unsafe-inline'; object-src 'none'; font-src *; media-src 'none'; form-action 'self';
{"latest":{"version":"v10.04","prefix":"/rest/v10.04","doc":"/api/v10.04"},"v10.04":{"version":"v10.04","prefix":"/rest/v10.04","doc":"/api/v10.04"},"v1":{"version":"v1","prefix":"/rest/v1","doc":"/api/v1"}}v1 API support will be deprecated in firmware version 10.09
Best practice while building automations using AOS-CX REST API is to use the latest API version that's supported by that platform. For the example above, v10.04 is the latest version and therefore should be use for all REST API commands:
curl -i -k -X POST "https://10.100.222.115/rest/v10.04/login?username=admin&password=admin" -H "accept: */*" -d ""
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Aug 2021 02:29:01 GMT
Content-Length: 0
Connection: keep-alive
Set-Cookie: id=RKUEgJ2kxkKW4tgF38qFRA==; Path=/; HttpOnly; Secure
Set-Cookie: user=eyJ1c2VyIjoiYWRtaW4iLCJsZXZlbCI6MTUsInR5cGUiOiJMT0NBTCIsIm1ldGhvZCI6IkxPQ0FMIn0=; Path=/; Secure
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'unsafe-inline'; object-src 'none'; font-src *; media-src 'none'; form-action 'self';
curl -i -k -X GET "https://10.100.222.115/rest/v10.04/system/vlans" -H "accept: */*" -d "" --cookie "id=jNqS3Kz6Wl_9_71upGiP1Q=="
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Aug 2021 02:29:17 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 120
Connection: keep-alive
Etag: 27770bab47fb985d18daefc899ccd58c
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'unsafe-inline'; object-src 'none'; font-src *; media-src 'none'; form-action 'self';
{
"1": "/rest/v10.04/system/vlans/1",
"20": "/rest/v10.04/system/vlans/20",
"40": "/rest/v10.04/system/vlans/40"
}
For automations targeting firmware version 10.08+, best practice is to use versionless API prefix /rest/latest/'
Introduced in firmware version *_10_09_0000 is the new API support for versionless URIs with
/rest/latest/. This allows for REST API commands to be written and they will always be using the latest version.Lastly, returned URIs will include the same API version that was used in the original REST API command. See the following example output from a switch with *_10_09_0000.swi firmware, as the API version changes in the GET command so does the returned URIs for that resource:
curl -i -k -X GET "https://10.100.222.115/rest/v10.08/system/vlans" -H "accept: */*" -d "" --cookie "id=jNqS3Kz6Wl_9_71upGiP1Q=="
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Aug 2021 02:17:52 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 120
Connection: keep-alive
Etag: 0c600bc6854b53ab5a8dbf584814e265
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'unsafe-inline'; object-src 'none'; font-src *; media-src 'none'; form-action 'self';
{
"1": "/rest/v10.08/system/vlans/1",
"20": "/rest/v10.08/system/vlans/20",
"40": "/rest/v10.08/system/vlans/40"
}*Notice how the URIs change when the API version is changed in the original GET command:
curl -i -k -X GET "https://10.100.222.115/rest/v10.04/system/vlans" -H "accept: */*" -d "" --cookie "id=jNqS3Kz6Wl_9_71upGiP1Q=="
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Aug 2021 02:17:57 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 120
Connection: keep-alive
Etag: 27770bab47fb985d18daefc899ccd58c
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'unsafe-inline'; object-src 'none'; font-src *; media-src 'none'; form-action 'self';
{
"1": "/rest/v10.04/system/vlans/1",
"20": "/rest/v10.04/system/vlans/20",
"40": "/rest/v10.04/system/vlans/40"
}curl -i -k -X GET "https://10.100.222.115/rest/latest/system/vlans" -H "accept: */*" -d "" --cookie "id=jNqS3Kz6Wl_9_71upGiP1Q=="
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 10 Aug 2021 02:18:13 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 120
Connection: keep-alive
Etag: 2665fea434e66e6869989341013f823f
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'unsafe-inline'; object-src 'none'; font-src *; media-src 'none'; form-action 'self';
{
"1": "/rest/latest/system/vlans/1",
"20": "/rest/latest/system/vlans/20",
"40": "/rest/latest/system/vlans/40"
}v10.08
8400
XL.10.08.001 and later
8360
LL.10.08.001 and later
8325
GL.10.08.001 and later
8320
TL.10.08.001 and later
6400-6300
FL.10.08.001 and later
6200
ML.10.08.001 and later
6100
PL.10.08.001 and later
v10.04
8400
XL.10.04.001 and later
8325
GL.10.04.001 and later
8320
TL.10.04.001 and later
6400-6300
FL.10.04.001 and later
6200
ML.10.04.001 and later
v1
8400
XL.10.00.001 and later
8325
GL.10.03.001 and later
8320
TL.10.02.001 and later
6400-6300
FL.10.04.001 and later
6200
ML.10.04.001 and later
Updated 23 days ago
What's Next
| GET |