vSphere 7 Update 2 - REST API Modernization
VMware introduced the REST APIs with the release of vSphere 6.0. Since then, we have expanded the API coverage by introducing new REST APIs for vSphere. All REST APIs from 6.0 to 6.7 were served under /rest and referred to as old REST APIs. Starting from vSphere 7, REST APIs are served under /api and referred to as new REST APIs.
With the release of vSphere 7 Update 2, VMware announces the deprecation of old REST APIs. These are now replaced with the new REST /api.
Impact
There is no immediate impact from this. However, we encourage our customers and partners to replace old REST APIs with new REST APIs. Below are some of the details which will help you understand the scope of this change.
- Replacement for Old REST APIs
We have revamped all the old REST APIs and replaced those with the new REST API. The new REST APIs are served under /api instead of /rest. The old REST APIs are still available along with the new REST APIs and will continue to work as expected.
- No immediate impact
There is no immediate impact out of this change as the old REST APIs will continue to work. We are not removing the old REST APIs or their support. We intend to remove it only after 2 major vSphere releases, also subject to customer feedback.
- No impact to vSphere Automation SDK and CLIs
vSphere Automation SDKs and CLIs will not be impacted.
Deprecated APIs
Starting from vSphere 7.0 Update 2, You can get the list of deprecated APIs via vCenter UI. You can go to the developer center and check out for deprecated labels against respective APIs. You can toggle in between new and deprecated APIs labels to get the respective APIs information.
Alternately, visit https://developer.vmware.com/docs/vsphere-automation/latest/ to find the deprecated APIs and their replacement.
Benefits of having New APIs
The new REST APIs improves the usability aspect of the REST APIs. Let's take a look at how.
Simple JSON representation
New REST APIs render maps as simple JSON objects. Responses from the new REST APIs benefit RFC 8259 and deliver only the semantically important JSON payload without the value wrapper that was needed in the older APIs.
This is especially significant for resource creation APIs that now return string literal identifiers e.g. "vm-42". The now deprecated versions had to return JSON object as per RFC7159 e.g. '{"value": "vm-42"}'.
For Example, below is the response received from a new REST API compared to the old one.
| New REST API Response | Old REST API Response |
|---|---|
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"TINY": {
"default_pod_cidr": {
"address": "10.244.0.0",
"prefix": 21
},
"num_supported_pods": 1000
},
"SMALL": {
"default_pod_cidr": {
"address": "10.244.0.0",
"prefix": 20
},
"num_supported_pods": 2000
}
} |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"value": [
{
"value": {
"default_pod_cidr": {
"address": "10.244.0.0",
"prefix": 21
},
"num_supported_pods": 1000
},
"key": "TINY"
},
{
"value": {
"default_pod_cidr": {
"address": "10.244.0.0",
"prefix": 20
},
"num_supported_pods": 2000
},
"key": "SMALL"
}
]
}
|
No Spec Wrapper
The new REST APIs provide cleaner JSON request body syntax without unnecessary levels of indirection. Specifically, the extra "spec" object seen in many of the old REST APIs has been removed.
| New REST API Response | Old REST API Response |
|---|---|
POST /api/vcenter/datacenter HTTP/1.1
Content-Type: application/json
{
"name": "req_map",
"folder": "folder-11"
} |
POST /rest/vcenter/datacenter HTTP/1.1
Content-Type: application/json
{
"spec": {
"name": "req_map",
"folder": "folder-11"
}
} |
Consistent Error representation
While consuming the REST APIs, you can potentially get errors either from the core infrastructure or from the API execution engine. In the past, it was difficult to handle the error response as the response schema would differ based on the source of the error.
With the new REST APIs, You now get a single error schema irrespective of the source of an error.
| New REST API Error Response | Old REST API Error Response |
|---|---|
{
"errorType": "...",
"messages": [{
"args": [],
"default_message": "..",
"id": ".."
}]
} |
{
"name": "..",
"localizableMessages": [{
"defaultMessage": "..",
"id": ".."
}],
"majorErrorCode": "..", "type": "..",
"value": {
"messages": [{
"args": [],
"default_message": "..",
"id": ".."
}]
},
"errorType": "...",
"messages": [{
"args": [],
"default_message": "..",
"id": ".."
}]
} |
URL improvements
With the new REST APIs, query parameters are simple non-hierarchical names and there is no need to provide indices for array parameters.
| New REST API URL | Old REST API URL |
|---|---|
GET /api/vcenter/namespace-management/stats/time-series &clusters=obj-103 &clusters=obj-104 &pod_name=string &namespace=obj-103 &obj_type=CLUSTER |
GET /rest/vcenter/namespace-management/stats/time-series
&spec.clusters.1=obj-103
&spec.clusters.2=obj-104
&spec.pod.pod_name=string
&spec.pod.namespace=obj-103
&spec.obj_type=CLUSTER |
Conclusion
The new REST APIs have a simplified schema and improved presentation layer, which enhances the developer experience. We recommend reviewing your automation workflows and replacing old REST APIs with the new ones at your own pace. There is no immediate impact because of this change as the old REST APIs are still available and supported for at least 2 major vSphere releases.