REST APIs introduced in vSphere 7.0 Update 2
Article ID: 320077
Updated On:
Products
Issue/Introduction
With vSphere 7.0 Update 2, VMware announces deprecation of old REST APIs introduced in vSphere 6.x. Old REST APIs are the APIs that was served under the /rest. Replacement of these APIs are also provided with this release. these APIs are served under /api.
Impact:
There is no immediate impact from this change.
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.
Environment
Resolution
We have introduced the new REST APIs (exact replacement of the same feature api) served under /api. You can get more details about the api through the vSphere API explorer inside the vSphere client or visit Explore VMware API References to learn more about these changes.
These new apis provide the following improvements:
Simple JSON representation
New REST APIs render maps as simple JSON objects. In the JSON object representing map value the member names represent map keys and member values represent the map values. Old APIs rendered map value as array of objects with key and value members.
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 API |
OLD API |
|
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 API |
OLD API |
|
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 API |
OLD API |
|
{ "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 API |
OLD API |
|
GET /api/vcenter/namespace-management/stats/time-series
|
GET /rest/vcenter/namespace-management/stats/time-series
|
Additional Information
Feedback
