Nutanix Intentful API
Release 5.11.2
Home
Introduction
Getting Started
Authentication
Use Cases
network_security_rules
access_control_policies
batch
blackouts
whatif
categories
clusters
reports
directory_services
hosts
idempotence_identifiers
identity_providers
images
image_placement_policies
network_function_chains
alerts
ngt_policies
permissions
projects
protection_rules
recovery_plan_jobs
recovery_plans
remote_syslog_modules
remote_syslog_servers
roles
subnets
tasks
user_groups
users
vms
Powered by Stoplight

Components of a REST API

A REST API request and response can be classified into the following components.

The request URI consists of {URI-scheme} :// {URI-host} / {/} ? {query-string}.

  • URI scheme - Indicates the protocol that is used to transmit the request. For example, http or https.
  • URI host - Specifies the domain name or IP address of the server where the REST service endpoint is hosted. For example, prism.nutanix.com or 10.11.12.13.
  • Port number - Indicates the port number that is used for HTTP communications from the REST API clients to the REST API server.
  • Basepath - Indicates the URL prefix that is common to all the API server endpoints. For example, for https://10.11.12.13/PrismGateway/services/rest/v2.0/vms, the basepath is /PrismGateway/services/rest/v2.0.
  • Path parameters - Path parameters are part of the endpoint. For example, https://10.11.12.13/PrismGateway/services/rest/v2.0/vms/750eb5ba-2de0-4ca4-8d6f-786364817f94/, the UUID of the VM (750eb5ba-2de0-4ca4-8d6f-786364817f94) is a path parameter.
  • Query string parameters - Query string parameters appear after a question mark (?) in the endpoint. The question mark followed by the parameters and their values is referred as the query string. In the query string, each parameter is listed one right after the other with an ampersand (&). The order of the query string parameters does not matter. For example, https://10.11.12.13/PrismGateway/services/rest/v2.0/vms/750eb5ba-2de0-4ca4-8d6f-786364817f94?include_vm_disk_config=true, the include_vm_disk_config is a query parameter.

HTTP defines methods to indicate the desired action to be performed on the identified resource.

  • Get - Retrieves a resource
  • Post - Creates a resource
  • Put - Updates or creates within an existing resource
  • Delete - Removes the resource

HTTP request headers provide meta-information about a request. The request body contains the data that client wants to send to the server. For example, Content-Type and Content-Transfer-Encoding.

HTTP response headers provide meta-information about a response. The response consists of status code (three-digit number), content type, and body of the response.

  • 1xx - Informational - Communicates transfer protocol-level information.
  • 2xx - Success - Indicates that the client request is successfully accepted.
  • 3xx - Redirection - Indicates that the client must take some additional steps to complete an action.
  • 4xx - Client Error - Indicates that there is some error from the client side.
  • 5xx - Server Error - Indicates that there is some error from the server side.

Entity Structure

An entity structure comprises of the following components.

  • Metadata - Metadata provides high-level information about the related entity including entity uuid, kind, and spec_version.
  • Status - Status provides information about the current state of the related entity including entity name, state, and entity-specific status information.
  • Specification - For a GET request, the specification section of the JSON response displays similar information as status section. However, for of POST request, the specification section provide details of what should be the desired state of the entity. For example, you can use the following JSON payload to create a basic VM. The payload denotes the minimum parameters required to create a VM by using the V3 APIs. All the missing specification items like CPU and RAM are configured with default values.
{
  "spec": {
    "name": "NewVM",
    "resources": {}
  },
  "metadata": {
    "kind": "vm"
  }
}