API Versioning

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.13",
    "prefix": "/rest/v10.13",
    "doc": "/api/v10.13"
  },
  "v10.04": {
    "version": "v10.04",
    "prefix": "/rest/v10.04",
    "doc": "/api/v10.04"
  },
  "v10.08": {
    "version": "v10.08",
    "prefix": "/rest/v10.08",
    "doc": "/api/v10.08"
  },
  "v10.09": {
    "version": "v10.09",
    "prefix": "/rest/v10.09",
    "doc": "/api/v10.09"
  },
  "v10.10": {
    "version": "v10.10",
    "prefix": "/rest/v10.10",
    "doc": "/api/v10.10"
  },
  "v10.11": {
    "version": "v10.11",
    "prefix": "/rest/v10.11",
    "doc": "/api/v10.11"
  },
  "v10.12": {
    "version": "v10.12",
    "prefix": "/rest/v10.12",
    "doc": "/api/v10.12"
  },
  "v10.13": {
    "version": "v10.13",
    "prefix": "/rest/v10.13",
    "doc": "/api/v10.13"
  }
}

❗️
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.13 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"
}

API Behavior Changes Starting v10.08 and later

📘
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"
}

Supported API Versions per AOS-CX Switch Model and Firmware Version

Version	Model	Supported Firmware
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