RESTful APIの概要
RESTful APIにアクセスするには、 JSA コンソールで特定のURL(エンドポイント)にHTTPSリクエストを送信します。これらの要求を送信するには、選択したプログラミング言語に組み込まれている HTTP 実装を使用します。各要求には、認証情報と、要求を変更するパラメーターが含まれています。
JSA と API のバージョン
次の表に示すように、すべてのJSAバージョンにはREST APIバージョンがあります。
JSA バージョン |
導入されたREST APIバージョン |
サポートされている REST API バージョン |
非推奨の REST API バージョン |
|---|---|---|---|
| 7.5.0 |
17.0 |
17.0 16.0 15.0 |
14.x |
| 7.4.3 |
16.0 |
16.0 15.0 14.0 |
13.x |
| 7.4.2 |
15.0 |
15.0 14.0 13.1 13.0 |
12.x |
| 7.4.1 |
14.0 |
14.0 13.1 13.0 12.1 12.0 |
11.x |
| 7.4.0 フィックスパック 1 |
13.1 |
13.1 13.0 12.1 12.0 |
10.x |
| 7.4.0 |
13.0 |
13.0 12.1 12.0 |
10.x |
| 7.3.3 フィックスパック3 |
12.1 |
12.1 12.0 11.0 |
10.x |
| 7.3.3 |
12.0 |
12.0 11.0 |
10.1 10.0 |
| 7.3.2 パッチ 3 |
11.0 |
11.0 10.1 10.0 |
9.2 9.1 9.0 |
| 7.3.2 パッチ 1 |
10.1 |
10.1 10.0 9.2 9.1 9.0 |
|
| 7.3.2 |
10.0 |
10.0 9.2 9.1 9.0 |
8.1 8.0 |
APIエンドポイント
API エンドポイント には、アクセスするリソースのURLと、そのリソースで完了するアクションが含まれています。アクションは、要求の HTTP メソッド (GET、POST、PUT、または DELETE) によって示されます。
APIへのアクセスに必要な権限
認証情報は、すべての API 要求に HTTP ヘッダーとして含める必要があります。次のいずれかの方法で、必要なアクセス資格情報を指定します。
認証ヘッダーに指定されている JSA ユーザーのユーザー名とパスワード。
ユーザー名とパスワードを指定するには、HTTP 基本認証を使用します。すべての要求に対してユーザー名とパスワードを指定することで API 要求を行うことができますが、JSA とのすべての API 統合には承認済みサービス トークンを使用します。ユーザー名とパスワードのオプションのみが、ドキュメンテーションページの表示にサポートされています。
ユーザーロール、セキュリティプロファイル、およびユーザーの作成の詳細については、 Juniper Secure Analytics管理ガイドを参照してください。
SEC ヘッダーに指定されている許可サービス・トークン。
承認されたサービスとして認証するには、承認されたサービスを使用する認証トークンを作成します。 JSA 認定サービスには、さまざまなAPIリソースへのアクセスを制御するロールとセキュリティプロファイルが割り当てられています。
トークンは、承認されたサービスの作成時に指定した有効期限まで有効です。
ユーザーロール、セキュリティプロファイル、および承認サービスの作成の詳細については、 Juniper Secure Analytics管理ガイドを参照してください。
API 要求と応答
API リクエストを送信すると、サーバーは HTTP レスポンスを返します。HTTP 応答には、要求が成功したかどうかを示す状態コードと、応答本文の応答の詳細が含まれています。ほとんどのリソースでは、この応答を JavaScript Object Notation (JSON) として書式設定します。データの抽出に使用するプログラミング言語に組み込まれている JSON パッケージまたはライブラリを使用できます。
バージョン ヘッダー
バージョン ヘッダーを使用して、API の特定のバージョンを要求します。バージョン ヘッダーを指定しない場合は、最新バージョンの API が使用されるため、 JSA のアップグレード時に統合が中断される可能性があります。APIを使用するたびにバージョンヘッダーを指定すると、APIクライアントを壊すことなく、JSAの新しいバージョンにアップグレードしやすくなります。
APIは、セマンティックバージョニングのメジャーコンポーネントとマイナーコンポーネントを使用します。自然数は、API のメジャー バージョンを示すために使用されます (例: '3')。API のマイナー バージョンは、メジャー コンポーネントとマイナー コンポーネントで指定されます (例: '3.1')。バージョン ヘッダーは、API のメジャー バージョンまたはマイナー バージョンに設定できます。既存のバージョンと互換性のある変更は、マイナー バージョン番号がインクリメントされて導入されます。互換性のない変更は、メジャー バージョン番号の増分とともに導入されます。
マイナー コンポーネントなしでバージョン ヘッダーで API のメジャー バージョンが指定されている場合、サーバーはメジャー API バージョン内の最新のマイナー バージョンで応答します。たとえば、クライアントがバージョン「3」を要求した場合、サーバーはバージョン「3.1」で応答します。バージョン 3.0 を使用する場合は、バージョン ヘッダーで '3.0' を要求する必要があります。エンドポイントの最新バージョンよりも新しいバージョンを要求すると、そのエンドポイントの使用可能な最新バージョンが返されます。各エンドポイントは、新しいバージョンで変更されていない場合でも、有効なすべてのバージョンの下に一覧表示されます。
エンドポイントの廃止
APIエンドポイントは、使用が推奨されておらず、将来のリリースで削除されることを示すために 非推奨 としてマークされます。統合に代替手段を使用する時間を与えるために、非推奨のエンドポイントは、削除される前に少なくとも 1 つのリリースで機能し続けます。対話型 API ドキュメント ページには、エンドポイントが非推奨としてマークされていることが示されています。また、非推奨のエンドポイントの API 応答メッセージには、ヘッダー Deprecatedが含まれます。個々の API エンドポイント、または API エンドポイントのバージョン全体を非推奨としてマークできます。非推奨のエンドポイントは、削除されるまで機能し続けます。
APIエンドポイントは、非推奨プロセスを完了すると削除されます。削除されたエンドポイントは正常に応答しなくなります。削除されたエンドポイントを呼び出そうとすると、エラーが返されます。削除された個々のエンドポイントに対して HTTP 410 Gone 応答が返されます。サポートされなくなったバージョンの要求に対しては、 HTTP 422 Unprocessable Entity 応答が返されます。
バージョン ヘッダーを API 要求に含めて、特定のバージョンの API エンドポイントを呼び出します。特定のバージョンを明示的にリクエストしないAPI統合はサポートされていません。バージョンを指定しない場合、要求は使用可能な最新バージョンに送られます。リリースに互換性のない新しいバージョンのエンドポイントが含まれている場合、統合が壊れる可能性があります。要求バージョンをコード内の 1 つの場所に保持して、新しいバージョンが利用可能になったときにアップグレードを容易にします。