Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
項目一覧
 

RESTful APIの概要

Representational State Transfer (REST) について理解し、Juniper Mist™ で RESTful API を使用する方法を理解します。

Juniper Mist の 100% API アーキテクチャは、Juniper Mist ポータルに表示されるすべての機能をバックアップします。ポータルでできることはすべて、API を使用して大規模に自動化できます。Representational State Transfer(REST)は、統一されたインターフェイスを備えたステートレスなクライアント/サーバーアーキテクチャです。マシンはユーザーインターフェイスを使用しないため、APIを使用すると、マシンが相互に通信するための定義された高速な方法が可能になります。

REST API を使用すると、システムやアプリケーションと対話する独自の方法を作成できます。カスタム機能を作成することもできます。REST APIのその他の一般的なユースケースには、アプリケーション間の通信とデータ交換、アプリケーションとサーバー間のデータ交換、アプリケーション内のマイクロサービス間の通信などがあります。RESTはステートレスであるため、クラウドベースのサービスに最適です。

Juniper Mist APIは、Juniper Mistアカウントを持つすべてのお客様が利用できます。

Mist API リファレンスも参照してください。これには、開発者向けの追加のドキュメントと、API 呼び出しをテストする機能が含まれています。

Juniper Mist APIアーキテクチャ

Juniper Mistは、HTTP メソッド(GET、POST、PUT、DELETE)を使用して JavaScript Object Notation (JSON) 形式でデータを転送する REST API を使用します。

RESTful APIリクエスト

RESTful API の使用は、開発で使用される CRUD (CREATE、READ、UPDATE、DELETE) 手法と同様の方法に従います。これらは、データを操作するときに使用される 4 つの基本的なアクションまたは関数です。

表 1: 基本的な CRUD アクション
CRUD HTTP/REST
創造する 投稿
読む 取得
更新 置く
削除 削除

APIエンドポイントURLの形式

API エンドポイント URL には、次の 2 つの部分があります。

  • API ホスト (またはエンドポイント) — Juniper Mist組織が関連付けられているグローバルリージョンのエンドポイント。これらのエンドポイントは、「 APIエンドポイント」および「グローバル・リージョン」にリストされています。

  • 関数 - API エンドポイントの後のすべては、API が呼び出す関数を表します。

例

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

手記：

コードブロックを再利用する場合は、プレースホルダー値を実際の値(APIトークン、組織ID、サイトID、AP名など)に置き換えます。

{api-host} の後はすべて関数です。コールはグローバル クラウドに送信され、指定されたサイトにある指定されたデバイスの統計情報を要求します。

次のセクションでは、API 呼び出しを構成する構造について詳しく説明します。

API 呼び出し構造

次の画像は、API 呼び出しとそれを構成するさまざまなコンポーネントの例です。

表 2: API 呼び出しコンポーネント

APIコールコンポーネント

形容

HTTP メソッド

  • POST—オブジェクトを作成します。- POSTは、既存の値をペイロードに含まれる値で上書きします。POST ペイロードで指定されていない値は、元の値に戻されます。

  • GET - オブジェクトのリスト。- GET は、識別子が指定されているかどうかに応じて、リソースの値またはリソースのリストを返します。

    • GET /api/v1/orgs/:org_id

      指定された :org_id に基づいて組織に関する情報を返します。

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

      :org_idに属するサイトのリストを返します。

    • GET /api/v1/sites/:site_id

      :site_id で指定されたサイトに関する情報を返します。

  • PUT—オブジェクトを更新します。- PUTは、ペイロード内の指定されたすべての値を変更します。PUTで更新する場合、ペイロードで指定されていない単純な値(文字列または数値)は既存の値を保持します。値に配列やオブジェクトなどのデータ構造が含まれている場合、ペイロードに含まれる値によってその構造全体が置き換えられます。既存の値に望ましくない変更が加えられないように、この点に留意してください。

  • DELETE - オブジェクトを削除します。- DELETE はリソースを削除します。

ホスト(またはAPIエンドポイント)

使用するMist Cloudを決定します(グローバル01、EMEA 01など)。Juniper Mist組織が関連付けられているグローバルリージョンのエンドポイント。 「APIエンドポイントとグローバルリージョン」を参照してください。

バージョン

使用する API バージョン (現在、すべての API で v1 が使用されています)。

スコープ

要求が行われているレベルを示します。たとえば、msp、org、site、self、register、installer、const などがあります。

スコープ ID

使用するスコープを識別します。

オブジェクト

使用するオブジェクトのタイプ(デバイス、WLAN など)。

オブジェクトID

要求するオブジェクトを識別します。

REST API で上記の REST コマンド (POST、GET、PUT、DELETE) を実行するには、各要求で次のようないくつかの要件を満たす必要があります。

  • 認証：

    • APIトークン、Juniper Mistログイン認証情報、または外部OAuth2プロバイダーを使用して、認証プロセス中に自分が誰であるか、何にアクセスできるかを示すことができます。

    • さまざまな認証方法の詳細については、「 認証」を参照してください。

      手記：

      すでに manage.mist.com にログインしている場合は、新しいブラウザタブを開き、[https://api.mist.com/api/v1/self/apitokens]に移動して [POST ]ボタンをクリックするだけです。これにより、新しいAPIユーザートークンが自動的に作成されます。

      トークンの詳細については、「 API トークンの作成 」を参照してください。

  • HTTP ヘッダー: このヘッダーは、次のようにコンテンツと承認の種類を指定します。

    • Juniper Mist の場合、コンテンツ タイプは常に application/json です。

    • 認証は、トークンまたは Cookie (CSRF トークンとセッション ID を含む) にすることができます。

  • Juniper Mist組織が関連付けられているグローバルリージョンのエンドポイント。 「APIエンドポイントとグローバルリージョン」を参照してください。

  • JSON ペイロード

次の表は、RESTful API 要求を構成するさまざまな部分の例を示しています。

表 3: RESTful API リクエストの例

CRUD 操作

HTTPヘッダー認証

エンドポイント URL

ペイロード(JSON)

取得

APIトークン

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

  

削除

CSRF トークン、セッション ID

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

  

投稿

CSRF トークン、セッション ID

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

{[" "]}

置く

APIトークン

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

{"ssid" : "新しい名前"}

JSON ペイロード

関数が異なれば、JSON ペイロードに必要な要素も異なります。必要な詳細は、 API ドキュメントで確認できます。

以下は、サンプルの API 呼び出しと応答 (JSON ペイロード) です。

API 呼び出し:

応答(JSON ペイロード):

API レート制限

Juniper Mist では、API 呼び出しを 1 時間あたり 5,000 に制限しています。1 時間あたり 5,000 件を超える通話を行う必要がある場合は、 サポート チケットを作成します。

手記：

ブルートフォース攻撃を防ぐために、ログインAPI(/api/v1/login)は、3回のログイン失敗後にレート制限されます。

API 認証オプション

Juniper Mist API では、認証を要求するための 3 つのオプションを使用できます。

  • 基本認証 - トークン

  • HTTP ログイン:ユーザ名とパスワード

    • ダッシュボードのログインと似ています。

    • 二要素認証が可能です。

  • OAuth2

    • アカウントはOAuthプロバイダーにリンクされている必要があります。

    • ブラウザへのアクセスが必要です。

認証の詳細については、 Mist API リファレンスを参照してください。

単純な API の例

Django API インターフェイスは、API 内で CRUD 操作を実行できる Web ベースのインターフェイスです。「 Django Web インターフェイスを使用して API を変更する」を参照してください。

Django API インターフェイスを使用して、最初の API 呼び出しを行うことができます。Mistにログイン後、同じブラウザで新しいウィンドウを開き、URL https://api.mist.com/api/v1/selfを入力します。これは、Global 01 クラウドの URL です。別のクラウドを使用している場合、このURLは異なります。

これは、この API 呼び出しを GET /api/v1/selfにすることと同じです。

上記の結果には、関連付けられている組織とサイトに対して割り当てられた権限が表示されます。

関連資料