Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
SUR CETTE PAGE
 

Présentation de l’API RESTful

Familiarisez-vous avec le transfert d’état représentationnel (REST) et découvrez comment utiliser les API RESTful avec Juniper Mist™.

L’architecture 100 % API de Juniper Mist sauvegarde toutes les fonctionnalités visibles sur le portail Juniper Mist. Tout ce que vous pouvez faire sur le portail, vous pouvez l’automatiser à grande échelle à l’aide de l’API. Le Representational State Transfer (REST) est une architecture client/serveur sans état dotée d’une interface uniforme. Étant donné que les machines n’ont pas besoin d’une interface utilisateur, les API permettent aux machines de communiquer entre elles de manière définie et plus rapide.

Les API REST vous permettent de créer votre propre façon d’interagir avec les systèmes et les applications. Vous pouvez même créer des fonctionnalités personnalisées. Les API REST sont également couramment utilisées, notamment la communication et l’échange de données entre applications, l’échange de données entre applications et serveurs, la communication entre microservices au sein d’une application, etc. REST est sans état, ce qui le rend idéal pour les services basés sur le cloud.

L’API Juniper Mist est disponible pour tout client disposant d’un compte Juniper Mist.

Consultez également la référence de l’API Mist. Il contient de la documentation supplémentaire pour les développeurs, ainsi que la possibilité de tester les appels d’API.

Juniper Mist API Architecture

Juniper Mist utilise des API REST, qui utilisent les méthodes HTTP (GET, POST, PUT et DELETE) pour transférer des données au format JSON (JavaScript Object Notation).

Requêtes d’API RESTful

L’utilisation d’API RESTful suit une pratique similaire à la méthodologie CRUD (CREATE, READ, UPDATE, DELETE) utilisée dans le développement. Ce sont les quatre actions ou fonctions de base utilisées lorsque vous travaillez avec des données.

Tableau 1 : Actions CRUD de base
CRUD HTTP/REST
Créer POST
Lire OBTENIR
Mise à jour METTRE
Supprimer SUPPRIMER

Format URL du point de terminaison de l’API

L’URL du point de terminaison de l’API comporte deux parties :

  • Hôte d’API (ou point de terminaison) : point de terminaison de la région globale à laquelle votre organisation Juniper Mist est associée. Ces points de terminaison sont répertoriés dans Points de terminaison d’API et Régions globales.

  • Fonction : tout ce qui se trouve après le point de terminaison de l’API représente la fonction que l’API appelle.

Exemple

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

Remarque :

Lorsque vous réutilisez des blocs de code, remplacez les valeurs d’espace réservé par des valeurs réelles, telles que votre jeton d’API, votre ID d’organisation, votre ID de site, votre nom d’AP, etc.

Tout ce qui suit {api-host} est la fonction. L’appel est dirigé vers le cloud global et demande les statistiques de l’appareil spécifié sur le site spécifié.

La section suivante examine plus en détail la structure qui compose un appel d’API.

Structure des appels d’API

L’image suivante est un exemple d’appel d’API et des différents composants qui le composent.

Tableau 2 : composants d’appel d’API

Composant d’appel d’API

Descriptif

Méthode HTTP

  • POST : crée un objet. : POST remplace toutes les valeurs existantes par celles contenues dans la charge utile. Les valeurs qui ne sont pas spécifiées dans la charge utile POST sont rétablies à leurs valeurs d’origine.

  • GET : répertorie les objets. : GET renvoie la valeur d’une ressource ou d’une liste de ressources, selon qu’un identificateur est spécifié ou non.

    • GET /api/v1/orgs/:org_id

      Renvoie des informations sur l’organisation en fonction du :org_id spécifié.

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

      Renvoie une liste de sites appartenant à : org_id.

    • GET /api/v1/sites/:site_id

      Renvoie des informations sur le site spécifié par : site_id.

  • PUT : met à jour un objet. : PUT modifie toutes les valeurs spécifiées dans la charge utile. Lors de la mise à jour avec un PUT, les valeurs simples (chaînes ou nombres) non spécifiées dans la charge utile conservent leurs valeurs existantes. Si la valeur contient une structure de données telle qu’un tableau ou un objet, les valeurs incluses dans la charge utile remplaceront cette structure dans son intégralité. Gardez cela à l’esprit pour éviter les modifications indésirables des valeurs existantes.

  • DELETE (DELETE) : supprime un objet.

Hôte (ou point de terminaison API)

Détermine le Mist Cloud à utiliser (Global 01, EMEA 01, etc.). Le point de terminaison de la région du monde à laquelle votre organisation Juniper Mist est associée. Voir Points de terminaison d’API et régions globales.

Version

La version de l’API à utiliser (actuellement, toutes les API utilisent la v1).

Domaine d’application

Indique le niveau auquel la demande est traitée. Par exemple, msp, org, site, self, register, installer, const, etc.

ID de portée

Identifie l’étendue à utiliser.

Objet

Type d’objet à utiliser (Appareil, WLAN, etc.).

ID d’objet

Identifie l’objet à demander.

Pour exécuter l’une des commandes REST ci-dessus (POST, GET, PUT, DELETE) sur l’API REST, vous devez remplir quelques exigences dans chaque requête, telles que :

  • Authentification :

    • Vous pouvez utiliser un jeton d’API, des identifiants de connexion Juniper Mist (ce type d’authentification sera obsolète en septembre 2026) ou un fournisseur OAuth2 externe pour indiquer qui vous êtes et ce à quoi vous avez accès pendant le processus d’authentification.

    • Pour plus de détails sur les différentes méthodes d’authentification, voir Authentification.

      Remarque :

      Si vous êtes déjà connecté sur manage.mist.com, il vous suffit d’ouvrir un nouvel onglet du navigateur et d’accéder à https://{api-host}/api/v1/self/apitokens et de cliquer sur le bouton POST . Cela créera automatiquement un nouveau jeton utilisateur api. Pour connaître votre hôte (point de terminaison d’API), consultez Points de terminaison d’API et régions globales.

      Voir Créer des jetons d’API pour plus d’informations sur les jetons.

  • En-tête HTTP : Cet en-tête spécifie le contenu et le type d’autorisation, comme suit :

    • Pour Juniper Mist, le type de contenu est toujours application/json.

    • L’autorisation peut prendre la forme d’un jeton ou d’un cookie (y compris le jeton CSRF et l’ID de session).

  • Le point de terminaison de la région du monde à laquelle votre organisation Juniper Mist est associée. Voir Points de terminaison d’API et régions globales.

  • Charge utile JSON

Le tableau suivant fournit des exemples des différentes parties qui composent une demande d’API RESTful.

Tableau 3 : exemples de requêtes d’API RESTful

Opération CRUD

Authentification de l’en-tête HTTP

URL du point de terminaison

Charge utile (JSON)

OBTENIR

Jeton d’API

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

  

SUPPRIMER

Jeton CSRF, ID de session

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

  

POST

Jeton CSRF, ID de session

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

{["<claim_code>"]}

METTRE

Jeton d’API

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

{"ssid » : « Nouveau nom"}

Charge utile JSON

Différentes fonctions nécessitent différents éléments dans la charge utile JSON. Vous pouvez afficher les détails requis dans la documentation de l’API.

Voici un exemple d’appel d’API et la réponse (charge utile JSON).

Appel API :

Réponse (charge utile JSON) :

Limitation du débit de l’API

Juniper Mist limite les appels d’API à 5 000 par heure. Si vous devez passer plus de 5 000 appels par heure, créez un ticket d’assistance.

Pour les déploiements de grande envergure, il est recommandé d’effectuer des appels d’API au niveau de l’organisation pour éviter d’atteindre rapidement la limite d’appels d’API.

Remarque :

Pour éviter les attaques par force brute, le débit de l’API de connexion (/api/v1/login) est limité après trois échecs de connexion.

Options d’authentification par API

L’API Juniper Mist offre trois options pour demander une authentification :

  • Authentification de base : jeton

    • Sécurisez-le comme un mot de passe.

    • Pour obtenir des instructions sur la création d’un jeton d’API, consultez Créer des jetons d’API.

    Attention : Pour renforcer la sécurité et s’aligner sur les meilleures pratiques du secteur, Mist rendra l’authentification de base obsolète pour tous les cas d’utilisation, y compris les connexions et les scripts d’administrateur, à compter de septembre 2026. Avant septembre 2026, toutes les intégrations devront passer à l’authentification basée sur des jetons afin de garantir un accès et une assistance ininterrompus. Voir Créer des jetons d’API.

  • Connexion HTTP : nom d’utilisateur et mot de passe

    • C’est comme une connexion sur un tableau de bord.

    • Il peut s’agir d’une authentification à deux facteurs.

  • OAuth2

    • Le compte doit être lié à un fournisseur OAuth.

    • Nécessite un accès au navigateur.

Pour plus d’informations sur l’authentification, consultez la référence de l’API Mist.

Un exemple simple d’API

L’interface API de Django est une interface Web dans laquelle vous pouvez effectuer des opérations CRUD dans l’API. Voir Utilisation de l’interface Web de Django pour apporter des modifications à l’API.

En utilisant l’interface API de Django, vous pouvez effectuer votre premier appel d’API. Après vous être connecté à Mist, ouvrez une nouvelle fenêtre en utilisant le même navigateur et entrez l’URL https://{api-host}/api/v1/self. Il s’agit de l’URL du Global 01 cloud. Si vous utilisez un autre cloud, cette URL sera différente.

Cela équivaut à effectuer cet appel GET /api/v1/selfd’API .

Le résultat, illustré ci-dessus, affiche les privilèges qui vous sont attribués pour les organisations et les sites auxquels vous êtes associé.

Documentation connexe