Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
EN ESTA PÁGINA
 

Descripción general de la API RESTful

Familiarícese con la transferencia de estado representacional (REST) y comprenda cómo puede usar las API RESTful con Juniper Mist™.

La arquitectura 100 % API de Juniper Mist respalda todas las características visibles en el portal de Juniper Mist. Cualquier cosa que pueda hacer en el portal, puede automatizarla a escala mediante la API. La transferencia de estado representacional (REST) es una arquitectura cliente/servidor sin estado con una interfaz uniforme. Dado que las máquinas no tienen ningún uso para una interfaz de usuario, las API permiten una forma definida y más rápida para que las máquinas se comuniquen entre sí.

Las API de REST le permiten crear su propia forma de interactuar con sistemas y aplicaciones. Incluso puede crear características personalizadas. Otros casos de uso comunes de las API de REST incluyen la comunicación y el intercambio de datos entre aplicaciones, el intercambio de datos entre aplicaciones y servidores, la comunicación entre microservicios dentro de una aplicación y más. REST no tiene estado, lo que lo hace ideal para servicios basados en la nube.

La API de Juniper Mist está disponible para cualquier cliente con una cuenta de Juniper Mist.

Consulte también la Referencia de la API de Mist. Contiene documentación adicional para los desarrolladores, así como la capacidad de probar las llamadas a la API.

Arquitectura de la API de Juniper Mist

Juniper Mist utiliza API de REST, que utilizan métodos HTTP (GET, POST, PUT y DELETE) para transferir datos en formato de notación de objetos JavaScript (JSON).

Solicitudes API RESTful

El uso de API RESTful sigue una práctica similar a la metodología CRUD (CREATE, READ, UPDATE, DELETE) utilizada en el desarrollo. Estas son las cuatro acciones o funciones básicas que se utilizan cuando se trabaja con datos.

Tabla 1: Acciones básicas de CRUD
CRUD HTTP/REST
Crear PUBLICAR
Leer OBTENER
Actualización PONER
Eliminar ELIMINAR

Formato de URL del punto de conexión de la API

La dirección URL del punto de conexión de API consta de dos partes:

  • Host de API (o punto de conexión): el punto de conexión de la región global a la que está asociada su organización de Juniper Mist. Estos puntos de conexión se enumeran en Puntos de conexión de API y Regiones globales.

  • Función: todo lo que se encuentra después del punto de conexión de la API representa la función a la que llamará la API.

Ejemplo

https://{api-host}/api/v1/sites/{site_id}/stats/devices/{device_id}.

https://{api-host}/api/v1/sites/13b0ee00-121a-456e-84e0-ead3008bc2f2/stats/devices/00000000-0000-0000-1000-d420b08532eb

Nota:

Al reutilizar bloques de código, reemplace los valores de marcador de posición por valores reales, como el token de API, el ID de organización, el ID de sitio, el nombre de AP, etc.

Todo lo que está después de {api-host} es la función. La llamada se dirige a la nube global y solicita las estadísticas para el dispositivo especificado en el sitio especificado.

En la siguiente sección, se analiza en mayor profundidad la estructura que constituye una llamada a la API.

Estructura de llamadas a la API

La siguiente imagen es un ejemplo de una llamada a la API y los diferentes componentes que la componen.

Tabla 2: Componentes de llamada a la API

Componente de llamada a la API

Descripción

Método HTTP

  • POST: crea un objeto: POST sobrescribe los valores existentes con los contenidos en la carga. Los valores que no se especifican en la carga POST se revierten a sus valores originales.

  • GET: enumerar objetos.—GET devuelve el valor de un recurso o una lista de recursos, en función de si se especifica un identificador.

    • GET /api/v1/orgs/:org_id

      Devuelve información sobre la organización basada en el :org_id especificado.

    • GET /api/v1/orgs/:org_id/site

      devuelve una lista de sitios que pertenecen a :org_id.

    • GET /api/v1/sites/:site_id

      Devuelve información sobre el sitio especificado por :site_id.

  • PUT: actualiza un objeto: PUT modifica todos los valores especificados en la carga. Cuando se actualiza con un PUT, los valores simples (cadenas o números) no especificados en la carga mantienen sus valores existentes. Si el valor contiene una estructura de datos, como una matriz o un objeto, los valores incluidos en la carga reemplazará esa estructura en su totalidad. Tenga esto en cuenta para evitar cambios no deseados en los valores existentes.

  • ELIMINAR: eliminar un objeto: ELIMINAR elimina un recurso.

Host (o punto de conexión de API)

Determina la nube de Mist que se debe utilizar (Global 01, EMEA 01, etc.). El punto de conexión de la región global con la que está asociada su organización de Juniper Mist. Consulte Puntos de conexión de API y regiones globales.

Versión

La versión de la API que se va a utilizar (actualmente, todas las API utilizan la v1).

Alcance

Indica el nivel en el que se realiza la solicitud. Algunos ejemplos son msp, org, site, self, register, installer, const, etc.

ID de ámbito

Identifica el alcance a utilizar.

Objeto

El tipo de objeto que se va a utilizar (dispositivo, WLAN, etc.).

ID de objeto

Identifica el objeto que se va a solicitar.

Para ejecutar cualquiera de los comandos de REST anteriores (POST, GET, PUT, DELETE) en la API de REST, debe cumplir algunos requisitos en cada solicitud, como los siguientes:

  • Autentificación:

    • Puede usar un token de API, credenciales de inicio de sesión de Juniper Mist (este tipo de autenticación dejará de estar disponible en septiembre de 2026) o un proveedor de OAuth2 externo para indicar quién es usted y a qué tiene acceso durante el proceso de autenticación.

    • Para obtener más información sobre los distintos métodos de autenticación, consulte Autenticación.

      Nota:

      Si ya ha iniciado sesión en manage.mist.com, simplemente puede abrir una nueva pestaña del navegador e ir a https://{api-host}/api/v1/self/apitokens y hacer clic en el botón POST . Esto creará automáticamente un nuevo token de usuario de API. Para averiguar su host (punto de conexión de API), consulte Puntos de conexión de API y regiones globales.

      Consulte Creación de tokens de API para obtener más información sobre los tokens.

  • Encabezado HTTP: Este encabezado especifica el contenido y el tipo de autorización, como se indica a continuación:

    • Para Juniper Mist, el tipo de contenido siempre es application/json.

    • La autorización puede ser un token o una cookie (incluido el token CSRF y el ID de sesión).

  • El punto de conexión de la región global con la que está asociada su organización de Juniper Mist. Consulte Puntos de conexión de API y regiones globales.

  • Carga JSON

En la siguiente tabla, se proporcionan ejemplos de las diferentes partes que componen una solicitud de API RESTful.

Tabla 3: Ejemplos de solicitudes de API RESTful

Operación CRUD

Autenticación de encabezado HTTP

URL del punto de conexión

Carga (JSON)

OBTENER

API Token

https://api.mist.com/api/v1/sites/:site_id/wlans

  

ELIMINAR

Token CSRF, ID de sesión

https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id

  

PUBLICAR

Token CSRF, ID de sesión

https://api.mist.com/api/v1/orgs/:org_id/inventory

{["<claim_code>"]}

PONER

API Token

https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id

{"ssid" : "Nuevo nombre"}

Carga JSON

Diferentes funciones requieren diferentes elementos en la carga JSON. Puede ver los detalles necesarios en la documentación de la API.

A continuación, se muestra un ejemplo de llamada a la API y la respuesta (carga JSON).

Llamada a la API:

Respuesta (carga JSON):

Limitación de velocidad de API

Juniper Mist limita las llamadas a la API a 5000 por hora. Si necesita realizar más de 5,000 llamadas por hora, cree un ticket de soporte.

Para implementaciones grandes, se recomienda que realice llamadas a la API a nivel de organización para evitar alcanzar el límite de llamadas a la API rápidamente.

Nota:

Para evitar ataques de fuerza bruta, la API de inicio de sesión (/api/v1/login) tiene una velocidad limitada después de tres errores de inicio de sesión.

Opciones de autenticación de API

La API de Juniper Mist permite tres opciones para solicitar autenticación:

  • Autenticación básica: token

    • Asegúrelo como una contraseña.

    • Para obtener instrucciones sobre cómo crear un token de API, consulte Crear tokens de API.

    Atención: Para mejorar la seguridad y alinearse con las mejores prácticas de la industria, Mist dejará de usar la autenticación básica para todos los casos de uso, incluidos los inicios de sesión y los scripts de administrador, a partir de septiembre de 2026. Antes de septiembre de 2026, todas las integraciones deben pasar a la autenticación basada en tokens para garantizar el acceso y el soporte ininterrumpidos. Consulte Creación de tokens de API.

  • Inicio de sesión HTTP: nombre de usuario y contraseña

    • Es como un inicio de sesión en el panel de control.

    • Puede ser una autenticación de dos factores.

  • OAuth2

    • La cuenta debe estar vinculada a un proveedor de OAuth.

    • Requiere acceso a través del navegador.

Para obtener más información sobre la autenticación, consulte la Referencia de la API de Mist.

Un ejemplo sencillo de API

La interfaz de la API de Django es una interfaz basada en web en la que puede realizar operaciones CRUD dentro de la API. Consulte Uso de la interfaz web de Django para realizar cambios en la API.

Con la interfaz de la API de Django, puede realizar su primera llamada a la API. Después de iniciar sesión en Mist, abra una nueva ventana con el mismo navegador e ingrese la URL https://{api-host}/api/v1/self. Esta es la URL de la nube Global 01. Si está utilizando otra nube, esta URL será diferente.

Esto equivale a realizar esta llamada GET /api/v1/selfa la API .

El resultado, que se muestra arriba, muestra los privilegios que se le han asignado para las organizaciones y los sitios a los que está asociado.

Documentación relacionada