HTTP Requests

Requests to the Intersight RESTful API are made to a resource's Uniform Resource Identifier (URI) and elicit a response in JSON format. Intersight maps standard HTTP methods to RESTful operations. The Intersight API supports the following HTTP methods:

• GET
• POST
• PATCH
• DELETE

The POST and DELETE methods are idempotent, meaning that there is no additional effect if they are called more than once with the same input parameters. The GET method is nullipotent, meaning that it can be called zero or more times without making any changes (or that it is a read-only operation). The PATCH method may or may not be idempotent, depending on the value of the Content-Type HTTP header. When the Content-Type header is set to application/json, the PATCH method is idempotent. When the Content-Type header is set to application/json-patch+json, the PATCH method may not be idempotent. For further details, see RFC 5789.

As an exception to the above rules, the Intersight search suggester API uses the POST method for complex read-only queries, in which case the POST method is nullipotent.

Semantic of HTTP Methods for Collection of Resources

Semantic of HTTP Methods for Single Resource

Supported HTTP Request Headers

Supported HTTP Response Headers

'Content-Type' HTTP Header

The 'Content-Type' HTTP header specifies the format of the body in the HTTP Request. Supported values for the 'Content-Type' depend on the HTTP method:

For GET and DELETE requests, the HTTP request body must be empty and the 'Content-Type' header is not applicable. An HTTP error is returned if the request body is not empty.

Content-Type: application/json

The 'application/json' Content-Type value is supported for POST and PATCH requests. In that case, the HTTP request body must include a JSON document that complies with the Intersight OpenAPI schema. The request may include a full or sparse JSON document.

When the HTTP request body is a full JSON document, the entire addressed resource is set or replaced with the input JSON document. The outcome is the same for POST and PATCH. When the HTTP request body is a sparse JSON document (i.e. the input document does not contain all properties defined in the Intersight OpenAPI specification), the Intersight Web service applies the input sparse document to the target resource. Properties specified in the input document are applied to the target resource, and other properties are retained as is. When the input document contains an array, the array must contain all elements, and the array in the target resource will be replaced with the entire input array; it is not possible to insert, replace, or modify a specific element in an array. Alternatively, use Content-Type 'application/json-patch+json' to insert, replace or delete specific elements in an arrays.

HTTP POST Request With Sparse Document

Consider a Server Profile resource with the following JSON document representation. >Note: This is a simplified example for illustration purpose. In the Intersight object model, the Server Profile contains additional properties that are not shown below.

{
  "Moid":        "5a5f30237a6d67337212e705",
  "CreateTime":  "2018-01-17T11:14:43.299Z",
  "ModTime":     "2018-01-17T11:14:43.3Z",
  "ObjectType":  "server.Profile",
  "Tags": [
    {"Key": "Site", "Value": "London"}
  ],
  "Name":        "hyperflex-node-1",
  "Description": "HyperFlex node",
  "AssignedServer": {
        "ObjectType": "compute.RackUnit",
        "Moid": "5b3e30963062393835e24e33"
  },
}

In this particular example, the resource URI that identifies the "hyperflex-node-1" Server Profile is https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705, hence the API client sends a POST request addressed at this URI.

Suppose the API client wants to modify the Name property of the Server Profile resource from "hyperflex-node-1" to "hyperflex-node-2" and update the Description property. The client can send a POST request to the URI identifying the Server Profile resource with a sparse JSON document in the HTTP request body, i.e. only send the properties that are intended to be modified.

POST https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json
Body:
{
  "Name": "hyperflex-node-2",
  "Description": "HyperFlex node for the VDI application"
}

When the Intersight Web service processes the HTTP POST request, it will modify the "Name" and "Description" properties of the Server Profile and the other properties will be retained as is. Some properties like ModTime are automatically updated as a side-effect.

HTTP POST Request With Nested Array

An API client may send the following document to update the Tags properties. The nested array "Tags" must contain all elements in the array. The 'Tags' array specified in the HTTP body will completely replace the 'Tags' array in the target REST resource.

POST https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json
Body:
{
  "Tags": [
    {"Key": "Site",        "Value": "London"},
    {"Key": "Environment", "Value": "Scale"},
    {"Key": "Owner",       "Value": "Bob"}
  ],
}

If you want to change the value of the 'Environment' tag from 'Scale' to 'Staging', you must send all elements in the 'Tags' array as shown below.

POST https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json
Body:
{
  "Tags": [
    {"Key": "Site",        "Value": "London"},
    {"Key": "Environment", "Value": "Staging"},
    {"Key": "Owner",       "Value": "Bob"}
  ]
}

If you intend to change the 'Environment' tag to 'Production' and you don't send all elements in the 'Tags' array, this will have the side-effect of deleting the 'Site' and 'Owner' tags. The API client must first read the existing Tags, modify them, and send the complete set of tags. To perform partial array modifications, it may be more appropriate to use the 'application/json-patch+json' Content-Type.

Content-Type: application/json-patch+json

The 'application/json-patch+json' Content-Type value is supported for PATCH requests only. A JSON patch document provides a method to perform partial modifications to REST resources (which are represented as JSON documents). For example, a JSON patch document can be used to insert, replace or delete a specific element in a JSON array.

A JSON patch document is written in a format that expresses a sequence of operations to apply to a target REST resource. The format of the PATCH document is specified in RFC 6902.

HTTP PATCH Request

The following is an example JSON Patch document used to modify a Server Profile:

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "test",    "path": "/Name",                "value": "hyperflex-node-2" },
  { "op": "add",     "path": "/Tags/-",              "value": {"Key": "Environment", "Value": "Production"} },
  { "op": "add",     "path": "/Tags/-",              "value": {"Key": "Site", "Value": "Dallas"} },
  { "op": "replace", "path": "/Name",                "value": "hyperflex-node-3" },
  { "op": "replace", "path": "/Description",         "value": "HyperFlex node for the VDI application" },
  { "op": "replace", "path": "/AssignedServer/Moid", "value": "5b3e30963062393835e24e34" },
  { "op": "replace", "path": "/AssignedServer",      "value": null }
]

Evaluation of a JSON Patch document begins against a target JSON document. Operations are applied sequentially in the order they appear in the array. Each operation in the sequence is applied to the target document; the resulting document becomes the target of the next operation. Evaluation continues until all operations are successfully applied or until an error condition is encountered. Operation objects must have exactly one "op" member, whose value indicates the operation to perform. Its value must be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors. Operation objects must have exactly one "path" member. That member's value is a string containing a JSON-Pointer value RFC6901 that references a location within the target document (the "target location") where the operation is performed.

The "move", and "copy" operators are not supported by the Intersight web service.

JSON Pointer

A JSON Pointer defines a string syntax for identifying a specific value within a JSON document. It is written as a list of tokens, each prefixed by /. Each token can be a string or a number. To reference an array element, you must either provide a numeric value, which is the index of the element in the array, or the single character "-", which refers to the end of the array. For example, given a JSON document:

{
  "Name" : "foo",
  "Tags" : [
    {"Key": "Site",        "Value": "London"},
    {"Key": "Environment", "Value": "Staging"},
    {"Key": "Owner",       "Value": "Bob"}
  ],
  "AssignedServer": {
        "ObjectType": "compute.RackUnit",
        "Moid": "5b3e30963062393835e24e33"
  }
}

The following JSON Pointers resolve this JSON as:

"/Name" → "foo"
"/Tags" → [
    {"Key": "Site",        "Value": "London"},
    {"Key": "Environment", "Value": "Staging"},
    {"Key": "Owner",       "Value": "Bob"}
  ]
"/Tags/0" → {"Key": "Site", "Value": "London"}
"/Tags/1" → {"Key": "Environment", "Value": "Staging"}
"/AssignedServer" → {
        "ObjectType": "compute.RackUnit",
        "Moid": "5b3e30963062393835e24e33"
  }
"/AssignedServer/ObjectType" → "compute.RackUnit"
"/AssignedServer/Moid" → "5b3e30963062393835e24e33"

An empty JSON Pointer "" (zero token) resolves to the whole JSON document.

JSON Path Extensions to JSON Pointer

Referencing an element in an array by its numeric index value is useful when the index value is known, but this may require sending a GET request prior to sending the PATCH request. This approach is susceptible to concurrency issues. For example, this could happen when an API client sends a GET request to determine the index of the array element, then sends a PATCH request after the document has been modified by another API client. Intersight supports JSON Path extensions on top of JSON pointer (as defined in RFC6901). The 'path' attribute of the JSON Patch supports array element references by value. For example, given the JSON document:

{
  "Name" : "foo"
  "Tags" : [
    {"Key": "Site",        "Value": "London"},
    {"Key": "Environment", "Value": "Staging"},
    {"Key": "Owner",       "Value": "Bob"}
  ],
  "AssignedServer": {
        "ObjectType": "compute.RackUnit",
        "Moid": "5b3e30963062393835e24e33"
  }
}

The following JSON Pointers resolve this JSON as:

"/Tags[Key='Site']"        → {"Key": "Site", "Value": "London"}
"/Tags/0"                  → {"Key": "Site", "Value": "London"}
"/Tags[Key='Environment']" → {"Key": "Environment", "Value": "Staging"}
"/Tags/1"                  → {"Key": "Environment", "Value": "Staging"}

HTTP PATCH Examples for the 'Tags' property

Given the following JSON document:

{
  "Name" : "foo",
  "Tags" : [
    {"Key": "Site",        "Value": "London"},
    {"Key": "Environment", "Value": "Staging"},
    {"Key": "Owner",       "Value": "Bob"}
  ],
  "AssignedServer": {
        "ObjectType": "compute.RackUnit",
        "Moid": "5b3e30963062393835e24e33"
  }
}

Send a request to remove Tag 'Owner' in a Server Profile. This PATCH request requires knowledge of the element index value in the array. >Note: This request could lead to unexpected results when multiple requests are received for the same document. If the array elements are shifted by another client before this request is received, the Intersight service may remove another element in the 'Tags' array.

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "remove",  "path": "/Tags/2" }
]

A more robust approach to delete the 'Owner' tag is to send the following PATCH request. This is more robust because the removal is independent of the element numerical index, which can help in the case of concurrent modifications for the same document.

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "remove",  "path": "/Tags[Key='Environment']" },
]

Add a new Tag 'Department' at the end of the 'Tags' array:

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "add",  "path": "/Tags/-", "value": {"Key": "Department", "Value": "123456"} }
]

Add a new Tag 'Department' as the first element of the 'Tags' array. Existing elements are shifted by one.

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "add",  "path": "/Tags/0", "value": {"Key": "Department", "Value": "123456"} }
]

Add a new Tag 'Department' at index value 1 in the 'Tags' array. Existing elements at index 1 and above are shifted by one.

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "add",  "path": "/Tags/1", "value": {"Key": "Department", "Value": "123456"} }
]

Add a new Tag 'Department' at the index value currently used by the 'Environment' tag. Existing elements at that index value and above are shifted by one.

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "add",  "path": "/Tags[Key='Environment']", "value": {"Key": "Department", "Value": "123456"} }
]

Change the value of the 'Environment' Tag to 'Production':

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "replace", "path": "/Tags/1", "value": {"Key": "Environment", "Value": "Production"} }
]

The same request can be performed by using a JSON pointer name reference instead of index value:

PATCH https://intersight.com/api/v1/Server/Profiles/5a5f30237a6d67337212e705
Content-Type: application/json-patch+json
Body:
[
  { "op": "replace", "path": "/Tags[Key='Environment']", "value": {"Key": "Environment", "Value": "Production"} }
]

Format of the JSON Documents in the HTTP Response Body

The HTTP response to a GET, POST and PATCH request always includes the updated JSON representation of the underlying resource.

The HTTP response to a DELETE request does not include the JSON representation of the underlying resource. The response to a DELETE request only includes the HTTP status code.

API Example

Request:

GET /api/v1/compute/PhysicalSummaries?$apply=groupby((Firmware), aggregate($count as count))
accept: \*/\*
accept-encoding: gzip, deflate, br
accept-language: en-US,en;q=0.9,fr-FR;q=0.8,fr;q=0.7
user-agent: Mozilla/5.0 (Macintosh; ...)

Response:

content-type:application/json; charset=utf-8
date:Thu, 25 Jan 2018 17:37:26 GMT
server:nginx
status:200
x-starship-traceid:NB9a7864a9f508a5b482107b1d9f124b93
Body:
{
  "Results": [
    {
      "Firmware": "3.1(2d)",
      "count": 204
    },
    {
      "Firmware": "3.1(2e)",
      "count": 76
    },
}