Servicios web REST

Last published : Oct 02, 2026
REST (Representational State Transfer) es un estilo arquitectónico basado en solicitudes y respuestas HTTP simples entre el cliente y el servidor. REST se utiliza para consultar o cambiar el estado de los objetos en el lado del servidor. En REST, el lado del servidor se modela como un conjunto de entidades donde cada entidad se identifica mediante una URL única.
Cada recurso también tiene un estado sobre el cual se pueden realizar las siguientes operaciones:
  • Crear. Los clientes pueden crear nuevos recursos del lado del servidor en un recurso "contenedor". Puede pensar en los recursos contenedores como carpetas y en los recursos secundarios como archivos o subcarpetas. El cliente que realiza la llamada proporciona el estado del recurso que se va a crear. El estado se puede especificar en la solicitud utilizando el formato XML o JSON. El cliente también puede especificar la URL única que identifica el nuevo objeto. Alternativamente, el servidor puede elegir y devolver una URL única que identifique el objeto creado. El método HTTP utilizado para las solicitudes de creación es POST.
  • Leer. Los clientes pueden recuperar el estado de un recurso especificando su URL con el método HTTP GET. El mensaje de respuesta contiene el estado del recurso, expresado en formato JSON.
  • Actualizar. Puede actualizar el estado de un recurso existente especificando la URL que identifica ese objeto y su nuevo estado en JSON o XML, utilizando el método HTTP PUT.
  • Eliminar. Puede destruir un recurso que existe en el lado del servidor utilizando el método HTTP DELETE y la URL que identifica el recurso que se va a eliminar.
Además de estas cuatro operaciones CRUD (Crear, Leer, Actualizar y Eliminar), los recursos pueden admitir otras operaciones o acciones. Estas operaciones utilizan el método HTTP POST, con el cuerpo de la solicitud en JSON especificando la operación a realizar y los parámetros para esa operación.
Las API de SDX NITRO se clasifican, según el alcance y el propósito de las API, en API de sistema y API de configuración.
Related information
API NITRO

API del sistema

El primer paso para usar NITRO es establecer una sesión con el dispositivo SDX y luego autenticar la sesión utilizando las credenciales del administrador.
Especifique el nombre de usuario y la contraseña en el objeto de inicio de sesión. El ID de sesión que se crea debe especificarse en el encabezado de la solicitud de todas las operaciones posteriores de la sesión.
Nota: Debe tener una cuenta de usuario en ese dispositivo. Las configuraciones que puede realizar están limitadas por el rol administrativo asignado a su cuenta.
Para conectarse a un dispositivo SDX con la dirección IP 10.102.31.16 utilizando el protocolo HTTPS:
  • URL https://10.102.31.16/nitro/v2/config/login/
  • Método HTTP POST
  • Solicitud
    • Encabezado
      Content-Type:application/vnd.com.citrix.sdx.login+json
      Nota: También se pueden usar tipos de contenido como 'application/x-www-form-urlencoded' que eran compatibles con versiones anteriores de NITRO. Asegúrese de que la carga útil sea la misma que se usaba en versiones anteriores. Las cargas útiles proporcionadas en esta documentación solo son aplicables si el tipo de contenido es del formato 'application/vnd.com.citrix.sdx.login+json'.
    • Carga útil
      {
          "login":
          {
              "username":"nsroot",
              "password":"verysecret"
          }
      }
  • Carga útil de respuesta
    • Encabezado
      HTTP/1.0 201 Created
      Set-Cookie:
      NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2
Nota: Utilice el ID de sesión en todas las operaciones NITRO posteriores en el dispositivo.
Nota: Por defecto, la conexión al dispositivo caduca después de 30 minutos de inactividad. Puede modificar el período de tiempo de espera especificando un nuevo período de tiempo de espera (en segundos) en el objeto de inicio de sesión. Por ejemplo, para modificar el período de tiempo de espera a 60 minutos, la carga útil de la solicitud es:
{
    "login":
    {
        "username":"nsroot",
        "password":"verysecret",
        "timeout":3600
    }
}
También puede conectarse al dispositivo para realizar una única operación, especificando el nombre de usuario y la contraseña en el encabezado de la solicitud de la operación. Por ejemplo, para conectarse a un dispositivo al crear una instancia de NetScaler:
  • URL
  • Método HTTP
  • Solicitud
    • Encabezado
      X-NITRO-USER:nsroot
      X-NITRO-PASS:verysecret
      Content-Type:application/vnd.com.citrix.sdx.ns+json
    • Carga útil
      {
          "ns":
          {
              ...
          }
      }
  • Respuesta.
    • Encabezado
      HTTP/1.0 201 Created
Para desconectar del dispositivo, utilice el método DELETE:
  • URL
  • Método HTTP DELETE
  • Solicitud
    • Encabezado
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.login+json

API de configuración

El protocolo NITRO se puede utilizar para configurar los recursos del dispositivo SDX.
Cada recurso SDX tiene una URL única asociada, dependiendo del tipo de operación a realizar. Las URL para operaciones de configuración tienen el formato: http://<IP>/nitro/v2/config/<resource_type>

Crear un recurso

Para crear un recurso (por ejemplo, una instancia de NetScaler) en el dispositivo SDX, especifique el nombre del recurso y otros argumentos relacionados en el objeto de recurso específico. Por ejemplo, para crear una instancia de NetScaler llamada vpx1:
  • URL
  • Método HTTP
  • Solicitud
    • Encabezado
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json
    • Carga útil
      {
          "ns":
          {
              "name":"vpx1",
              "ip_address":"192.168.100.2",
              "netmask":"255.255.255.0",
              "gateway":"192.168.100.1",
              "image_name":"nsvpx-9.3-45_nc.xva",
              "vm_memory_total":2048,
              "throughput":1000,
              "pps":1000000,
              "license":"Standard",
              "profile_name":"ns_nsroot_profile",
              "username":"admin",
              "password":"admin",
              "network_interfaces":
              [
                  {
                      "port_name":"10/1"
                  },
                  {
                      "port_name":"10/2"
                  }
              ]
          }
      }

Recuperar detalles y estadísticas de recursos

Los detalles de los recursos de SDX se pueden recuperar de la siguiente manera:
  • Para recuperar los detalles de un recurso específico en el dispositivo SDX, especifique el ID del recurso en la URL.
  • Para recuperar las propiedades de los recursos basándose en algún filtro, especifique las condiciones del filtro en la URL.
    La URL tiene el formato: http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>
  • Si es probable que su solicitud devuelva muchos recursos del dispositivo, puede recuperar estos resultados en fragmentos dividiéndolos en «páginas» y recuperándolos página por página.
    Por ejemplo, suponga que desea recuperar todas las instancias de NetScaler en un SDX que tiene 53 de ellas. En lugar de recuperar las 53 en una única respuesta grande, configure los resultados para que se dividan en páginas de 10 instancias de NetScaler cada una (6 páginas en total). Luego, recupérelas del servidor página por página.
    Puede especificar el recuento de páginas con el parámetro de cadena de consulta de tamaño de página y usar el parámetro de cadena de consulta de número de página para especificar el número de página que desea recuperar. La URL tiene el formato: http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>
    No es necesario recuperar todas las páginas ni recuperarlas en orden. Cada solicitud es independiente, e incluso puede cambiar la configuración del tamaño de página entre solicitudes.
    Nota: Para tener una idea del número de recursos que probablemente devolverá una solicitud, puede usar el parámetro de cadena de consulta de recuento para solicitar un recuento de los recursos que se devolverán, en lugar de los recursos en sí. Para obtener el número de instancias de NetScaler disponibles, la URL sería http://<IP>/nitro/v2/config/<resource_type>?count=yes
Para recuperar la información de configuración de la instancia de NetScaler con ID 123456a:
  • URL
  • Método HTTP GET

Actualizar un recurso

Para actualizar un recurso SDX existente, utilice el método HTTP PUT. En la carga útil de la solicitud HTTP, especifique el nombre y los demás argumentos que deben cambiarse. Por ejemplo, para cambiar el nombre de la instancia de NetScaler con ID 123456a a vpx2:
  • URL
  • Método HTTP
  • Carga útil de la solicitud
    • Encabezado
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json
    • Carga útil
      {
          "ns":
          {
              "name":"vpx2",
              "id":"123456a"
          }
      }

Eliminar un recurso

Para eliminar un recurso existente, especifique el nombre del recurso que se va a eliminar en la URL. Por ejemplo, para eliminar una instancia de NetScaler con ID 123456a:
  • URL
  • Método HTTP
  • Solicitud
    • Encabezado
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json

Operaciones masivas

Puede consultar o cambiar varios recursos simultáneamente y, de este modo, minimizar el tráfico de red. Por ejemplo, puede añadir varios dispositivos NetScaler SDX en la misma operación. También puede añadir recursos de diferentes tipos en una sola solicitud.
Para tener en cuenta el fallo de algunas operaciones dentro de la operación masiva, NITRO le permite configurar uno de los siguientes comportamientos:
  • Salir. Cuando se encuentra el primer error, la ejecución se detiene. Los comandos que se ejecutaron antes del error se confirman.
  • Continuar. Todos los comandos de la lista se ejecutan incluso si algunos comandos fallan.
Nota: Configure el comportamiento requerido en el encabezado de la solicitud utilizando el parámetro X-NITRO-ONERROR.
Para añadir 2 recursos de NetScaler en una operación y continuar si un comando falla:
  • URL.
  • Método HTTP.
  • Carga útil de la solicitud.
    • Encabezado
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json
      X-NITRO-ONERROR:continue
    • Carga útil
      {
          "ns":
          [
              {
                  "name":"ns_instance1",
                  "ip_address":"10.70.136.5",
                  "netmask":"255.255.255.0",
                  "gateway":"10.70.136.1"
              },
              {
                  "name":"ns_instance2",
                  "ip_address":"10.70.136.8",
                  "netmask":"255.255.255.0",
                  "gateway":"10.70.136.1"
              }
          ]
      }
Para añadir múltiples recursos (NetScaler y dos usuarios de MPS) en una operación y continuar si un comando falla:
  • URL.
  • Método HTTP. POST
  • Carga útil de la solicitud.
    • Encabezado
      Cookie:NITRO_AUTH_TOKEN=tokenvalue
      Content-Type:application/vnd.com.citrix.sdx.ns+json
      X-NITRO-ONERROR:continue
    • Carga útil
      {
          "ns":
          [
              {
                  "name":"ns_instance1",
                  "ip_address":"10.70.136.5",
                  "netmask":"255.255.255.0",
                  "gateway":"10.70.136.1"
              },
              {
                  "name":"ns_instance2",
                  "ip_address":"10.70.136.8",
                  "netmask":"255.255.255.0",
                  "gateway":"10.70.136.1"
              }
          ],
           "mpsuser":
          [
              {
                  "name":"admin",
                  "password":"admin",
                  "permission":"superuser"
              },
              {
                  "name":"admin",
                  "password":"admin",
                  "permission":"superuser"
              }
          ]
      }

Manejo de excepciones

El campo de código de error indica el estado de la operación.
  • Un código de error de 0 indica que la operación se realizó correctamente.
  • Un código de error distinto de cero indica un error al procesar la solicitud NITRO.
El campo de mensaje de error proporciona una breve explicación y la naturaleza del fallo.