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 REST (Representational State Transfer) et comprenez comment utiliser les API RESTful avec Juniper Mist™.

L’architecture 100 % API de Juniper Mist sauvegarde toutes les fonctionnalités visibles dans le portail Juniper Mist. Tout ce que vous pouvez faire dans le portail, vous pouvez l’automatiser à grande échelle à l’aide de l’API. REST (Representational State Transfer) est une architecture client/serveur sans état avec 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. Parmi les autres cas d’utilisation courants des API REST, citons la communication et l’échange de données entre les applications, l’échange de données entre les applications et les serveurs, la communication entre les 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 des 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 en développement. Il s’agit des quatre actions ou fonctions de base utilisées lors de l’utilisation de données.

Tableau 1 : Actions de base du CRUD
CRUD HTTP/REST
Créer PUBLIER
Lire AVOIR
Mettre à jour METTRE
Supprimer SUPPRIMER

Format d’URL du point de terminaison d’API

L’URL du point de terminaison d’API se compose de deux parties :

  • API Host (ou Endpoint) : 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.

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

Exemple

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

https://api.mist.com/api/v1/sites/13b0ee00-121a-456e-84e0-ead3008bc2f2/stats/devices/00000000-0000-0000-1000-d420b08532eb

Note:

Lorsque vous réutilisez des blocs de code, remplacez les valeurs d’espace réservé par des valeurs réelles, telles que votre jeton API, votre ID d’organisation, votre ID de site, le nom de votre point d’accès, 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 des appels d’API

Composant d’appel d’API

Description

Méthode HTTP

  • POST : crée un objet. POST (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 au :org_id.

    • GET /api/v1/sites/:site_id

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

  • PUT : met à jour un objet. : PUT modifie toutes les valeurs spécifiées dans la charge utile. Lors d’une 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 toute modification indésirable des valeurs existantes.

  • DELETE : supprime un objet.—DELETE supprime une ressource.

Hôte (ou point de terminaison d’API)

Détermine le Mist Cloud à utiliser (Global 01, EMEA 01, etc.). Point de terminaison de la région globale à laquelle votre organisation Juniper Mist est associée. Reportez-vous à la section Points de terminaison d’API et régions globales.

Version

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

Portée

Indique le niveau auquel la demande est traitée. Il peut s’agir, par exemple, de msp, d’org, de site, d’auto, de registre, d’installateur, de const, etc.

ID du champ d’application

Identifie le champ d’application à 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 API, Juniper Mist identifiants de connexion ou un fournisseur OAuth2 externe pour indiquer qui vous êtes et ce à quoi vous avez accès pendant le processus d’authentification.

    • Pour plus d’informations sur les différentes méthodes d’authentification, reportez-vous à la section Authentification.

      Note:

      Si vous êtes déjà connecté sur manage.mist.com, il vous suffit d’ouvrir un nouvel onglet de navigateur et d’aller sur https://api.mist.com/api/v1/self/apitokens et de cliquer sur le bouton POST . Cela créera automatiquement un nouveau jeton d’utilisateur d’API.

      Pour plus d’informations sur les jetons, consultez Créer des jetons d’API .

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

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

    • Il peut s’agir d’un jeton ou d’un cookie (y compris le jeton CSRF et l’ID de session).

  • Point de terminaison de la région globale à laquelle votre organisation Juniper Mist est associée. Reportez-vous à la section Points de terminaison d’API et régions globales.

  • Charge utile JSON

Le tableau suivant fournit des exemples pour les différentes parties qui composent une requête d’API RESTful.

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

Fonctionnement CRUD

Authentification de l’en-tête HTTP

URL du point de terminaison

Charge utile (JSON)

AVOIR

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

  

PUBLIER

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 consulter les détails requis dans la documentation de l’API.

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

Appel d’API :

Réponse (charge utile JSON) :

Limitation du débit de l’API

Juniper Mist limite le nombre d’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 afin d’éviter d’atteindre rapidement la limite d’appels d’API.

Note:

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

Options d’authentification via l’API

L’API Juniper Mist offre trois options pour demander l’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.

  • HTTP Login— Nom d’utilisateur et mot de passe

    • C’est comme une connexion au 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 par navigateur.

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

Un exemple d’API simple

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

En utilisant l’interface de l’API Django, vous pouvez effectuer votre premier appel d’API. Après vous être connecté à Mist, ouvrez une nouvelle fenêtre à l’aide du même navigateur et saisissez l’URL https://api.mist.com/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és.

Documentation connexe