REST Web Services (Servicios web de REST)

REST (Transferencia de estado representacional) es un estilo arquitectónico basado en solicitudes y respuestas HTTP simples entre el cliente y el servidor. REST se usa 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 en el que cada entidad se identifica mediante una URL única.

Cada recurso también tiene un estado en el que 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 llama proporciona el estado para que se cree el recurso. El estado se puede especificar en la solicitud mediante el formato XML o JSON. El cliente también puede especificar la URL única que identificará el nuevo objeto. Alternativamente, el servidor puede elegir y devolver una URL única que identifique el objeto creado. El método HTTP utilizado para crear solicitudes es POST.
• Lee. 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.
• Actualización. Puede actualizar el estado de un recurso existente; para ello, especifique la dirección URL que identifica ese objeto y su nuevo estado en JSON o XML, o bien utilice el método PUT HTTP.
• Borrar. Puede destruir un recurso que exista en el lado del servidor mediante el método HTTP DELETE y la URL que identifica el recurso que se va a eliminar.

Además de estas cuatro operaciones CLAE (Crear, Leer, Actualizar y Eliminar), los recursos pueden admitir otras operaciones o acciones. Estas operaciones utilizan el método HTTP POST, en el que el cuerpo de la solicitud en JSON especifica la operación que se va 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 del sistema y API de configuración.

APIs del sistema

El primer paso para utilizar NITRO es establecer una sesión con el dispositivo SDX y, a continuación, autenticar la sesión mediante las credenciales del administrador.

Debe especificar el nombre de usuario y la contraseña en el objeto de inicio de sesión. El identificador de sesión que se crea debe especificarse en el encabezado de 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 la función administrativa asignada a su cuenta.

Para conectarse a un dispositivo SDX con la dirección IP 10.102.31.16 mediante el protocolo HTTPS:

• URL https://10.102.31.16/nitro/v2/config/login/
• Método HTTP POST
• Solicitar

  • Header

    pre codeblock Content-Type:application/vnd.com.citrix.sdx.login+json <!--NeedCopy-->

    Nota: También se pueden utilizar tipos de contenido como “application/x-www-form-urlencoded” que se admitían en versiones anteriores de NITRO. Debe asegurarse de que la carga útil sea la misma que la utilizada en versiones anteriores. Las cargas útiles proporcionadas en esta documentación solo son aplicables si el tipo de contenido es de la forma ‘application/vnd.com.citrix.sdx.login + json’.

  • Payload

    pre codeblock { "login": { "username":"nsroot", "password":"verysecret" } } <!--NeedCopy-->

• Carga útil de respuesta

  • Header

    pre codeblock HTTP/1.0 201 Created Set-Cookie: NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2 <!--NeedCopy-->

Nota: Debe utilizar el ID de sesión en todas las operaciones de NITRO posteriores en el dispositivo.

Nota: De forma predeterminada, la conexión con el 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:

``` pre codeblock { “login”: { “username”:”nsroot”, “password”:”verysecret”, “timeout”:3600 } }

También puede conectarse al dispositivo para realizar una sola operación, especificando el nombre de usuario y la contraseña en el encabezado de solicitud de la operación. Por ejemplo, para conectarse a un dispositivo mientras se crea una instancia de Citrix ADC:

-  **URL**
-  **HTTP (método)**
-  **Solicitar**
    -  **Header**

        ``` pre codeblock
        X-NITRO-USER:nsroot
        X-NITRO-PASS:verysecret
        Content-Type:application/vnd.com.citrix.sdx.ns+json
        <!--NeedCopy-->

-  **Payload**

    ``` pre codeblock
    {
        "ns":
        {
            ...
        }
    }
    <!--NeedCopy--> ```

• Respuesta.

  • Header

    pre codeblock HTTP/1.0 201 Created <!--NeedCopy-->

Para desconectarse del dispositivo, utilice el método DELETE:

• URL
• Método HTTP DELETE
• Solicitar

  • Header

    pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.login+json <!--NeedCopy-->

API de configuración

El protocolo NITRO se puede usar para configurar los recursos del dispositivo SDX.

Cada recurso SDX tiene una URL única asociada, según el tipo de operación que se vaya a realizar. Las URL de las operaciones de configuración tienen el siguiente formato: http://<IP>/nitro/v2/config/<resource_type>

Creación de un recurso

Para crear un recurso nuevo (por ejemplo, una instancia de Citrix ADC) 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 Citrix ADC llamada vpx1:

• URL
• HTTP (método)
• Solicitar

  • Header

    pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy-->

  • Payload

    pre codeblock { "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" } ] } } <!--NeedCopy-->

Recuperación de detalles y estadísticas de recursos

Los detalles de los recursos SDX se pueden recuperar de la siguiente manera:

• Para recuperar los detalles de un recurso específico en el dispositivo SDX, especifique el identificador del recurso en la URL.

• Para recuperar las propiedades de los recursos en función de algún filtro, especifique las condiciones del filtro en la URL.

  La URL tiene el siguiente formato: http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>

• Si es probable que su solicitud produzca un gran número de recursos devueltos desde el dispositivo, puede recuperar estos resultados en fragmentos dividiéndolos en “páginas” y recuperándolos página por página.

  Por ejemplo, suponga que quiere recuperar todas las instancias Citrix ADC en un SDX que tenga 53 de ellas. En lugar de recuperar los 53 en una gran respuesta, puede configurar los resultados para que se dividan en páginas de 10 instancias de Citrix ADC cada una (6 páginas en total) y recuperarlos del servidor página por página.

  Especifique el recuento de páginas con el parámetro de cadena de consulta de tamaño de página y utilice el parámetro de cadena de consulta “pageno” para especificar el número de página que quiere recuperar. La URL tiene el siguiente formato: http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

  No tiene que recuperar todas las páginas ni recuperar las páginas en orden. Cada solicitud es independiente e incluso puede cambiar la configuración del tamaño de página entre solicitudes.

  Nota: Si quiere tener una idea del número de recursos que es probable que devuelvan una solicitud, puede utilizar el parámetro de cadena de consulta de recuento para solicitar un recuento de los recursos que se devuelvan, en lugar de los propios recursos. Para obtener la cantidad de instancias de Citrix ADC 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 Citrix ADC con ID 123456a:

• URL
• Método HTTP GET

Actualización de un recurso

Para actualizar un recurso SDX existente, use el método PUT HTTP. En la carga útil de la solicitud HTTP, especifique el nombre y los demás argumentos que se deben cambiar. Por ejemplo, para cambiar el nombre de la instancia de Citrix ADC con ID 123456a a vpx2:

• URL
• HTTP (método)
• Solicitar carga útil

  • Header

    pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy-->

  • Payload

    pre codeblock { "ns": { "name":"vpx2", "id":"123456a" } } <!--NeedCopy-->

Eliminación de un recurso

Para eliminar un recurso existente, especifique el nombre del recurso que se eliminará en la URL. Por ejemplo, para eliminar una instancia de Citrix ADC con ID 123456a:

• URL
• HTTP (método)
• Solicitar

  • Header

    pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json <!--NeedCopy-->

Operaciones a granel

Puede consultar o cambiar varios recursos simultáneamente y, por lo tanto, minimizar el tráfico de red. Por ejemplo, puede agregar varios dispositivos NetScaler SDX en la misma operación. También puede agregar recursos de diferentes tipos en una solicitud.

Para tener en cuenta el error de algunas operaciones dentro de la operación masiva, NITRO le permite configurar uno de los siguientes comportamientos:

• Salida. Cuando se encuentra el primer error, la ejecución se detiene. Se confirman los comandos que se ejecutaron antes del error.
• Continúe. Todos los comandos de la lista se ejecutan incluso si algunos comandos fallan.

Nota: Debe configurar el comportamiento requerido en el encabezado de solicitud mediante el parámetro X-NITRO-ONERROR.

Para agregar 2 recursos de Citrix ADC en una operación y continuar si falla un comando:

• URL.
• Método HTTP.
• Solicitar carga útil.

  • Header

    pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue <!--NeedCopy-->

  • Payload

    pre codeblock { "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" } ] } <!--NeedCopy-->

Para agregar varios recursos (Citrix ADC y dos usuarios de MPS) en una operación y continuar si falla un comando:

• URL.
• Método HTTP. POST
• Solicitar carga útil.

  • Header

    pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue <!--NeedCopy-->

  • Payload

    pre codeblock { "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" } ] } <!--NeedCopy-->

Gestión de excepciones

El campo errorcode indica el estado de la operación.

• Un código de error de 0 indica que la operación se ha realizado correctamente.
• Un código de error distinto de cero indica un error en el procesamiento de la solicitud NITRO.

El campo de mensaje de error proporciona una breve explicación y la naturaleza del error.