APIの理解: REST

 

セキュリティオーケストレーション、自動化、対応（SOAR） プラットフォームは、異なるセキュリティツール（製品）のオーケストレーションを推進し、アクションの形で必要なレスポンスを呼び出すために、API（アプリケーション・プログラミング・インターフェース）に大きく依存しています。SOAR製品以外にも、技術担当者が使用するほぼすべてのサービス、ツール、製品でAPIが一般的に利用されています。.

APIは非常に普及していますが、実際に使った経験がない、あるいはサービスとやり取りする際にAPIがあることすら知らないという人もいるかもしれません。例えば、FacebookはAPIフレームワークを使用しています。 グラフAPI.

“「Graph API は、アプリが Facebook ソーシャル グラフを読み書きするための主な方法です。」”

APIには様々な形式がありますが、どのAPIフレームワークをサービスに使用しても、技術者はシステムやサービスと連携することができます。APIを使用することで、単一のアプリケーション内部での開発からSwimlaneのような大規模なシステムまで、システムを迅速に開発し、接続することが可能になります。.

APIの利用により、世界中の個人（および組織）は、情報を迅速かつ安全に（もちろん適切に実装されている場合）、定義された（記述された）形式で共有し、やり取りできるようになります。APIがなければ、今日の自動化は存在しなかったでしょう。.

この 2 部構成のシリーズの第 1 部では、REST (Representable State Transfer) API の概要と、API の理解を深めるのに役立つ重要なポイントについて説明します。.

認証

REST APIは通常、APIとやり取りするために何らかの認証メカニズムを必要とします。これは有料の製品やサービスとやり取りする場合は標準的なものですが、オープンソースインテリジェンスツール（OSINT）やその他のインターネット上の無料サービスとやり取りする場合は必ずしも必要ではありません。.

APIが使用する標準およびカスタムの認証方法はいくつかあります。すべてを列挙することは不可能ですが、一般的には以下の種類の認証方法が使用されるでしょう。

タイプ	例	説明
認証なし	ThreatMinerのAPIをクエリし、ドメインgoogle.comを検索する	APIからデータをリクエストする際に追加情報を追加する必要がないAPI
ユーザー名とパスワード	Microsoft Exchange オンプレミス API のクエリ	ユーザー名とパスワードを使用した基本認証を必要とするAPI
トークン	haveibeenpwned.com にクエリを実行するには、無料アカウントと API トークンを作成する必要があります。.	API サービスを利用するには、固有のトークンが必要となる API です。通常、このトークンはリクエストのヘッダーで指定する必要があります。.
委任	OAuth2認証を必要とするMicrosoft Graph APIを使用する	API を使用するための一時的なトークンを提供する認証サービスと連携して動作する API。.

これらは、サービスが使用できる様々な認証メカニズムのほんの一例です。製品や企業によっては、上記のような標準規格を選択する場合もあれば、独自の認証メカニズムを使用する場合もあります。.

これらの認証メカニズムの主な目的は、ユーザーがサービスに対して正しいアクセス権を持っていることを確認することと、ユーザーがサービスの規定された使用制限内に留まっていることを確認することです。.

Microsoft の OAuth2 実装を詳しく知りたい場合は、この特定の認証メカニズムについて詳しく説明している、私が書いた 3 部構成のシリーズをご覧ください。 パート1, パート2, 、 そして パート3.

バージョン

今後は、架空のサービスである ジョシュの脅威インテリジェンスサービス このサービスの URL は次のとおりです。 https://joshsthreatintel.example.

このようなサイトにアクセスして、他の Web サイトと同じように操作することはできますが、その背後には、プログラムで情報にアクセスして自動化を促進できる API が含まれています。.

優れたAPIには、認証方法やサービスの利用方法の詳細を説明した優れたドキュメントが付属しています。一般的に使用される標準は次のとおりです。 威勢のいい, ただし、Swagger が何であるかを理解する必要はありません (Swagger は、API の迅速な開発と、API のドキュメント化に関する標準化を可能にする標準です)。.

で https://joshsthreatintel.example 当社のAPIはバージョン管理されており、 /v1 当社のURLにアクセスしてください。当社のウェブサイトからこのフォルダにアクセスすると、中身が空だったり、認証されていないという通知が表示されたり、APIのドキュメントを表示するページが表示されたりする可能性があります。いずれの場合も、APIのルートディレクトリへは次のURLでアクセスできます。 https://joshsthreatintel.example/v1/.

それぞれのAPIには、1つ以上のバージョンが存在する可能性があります。例えば、havibeenpwned.comには3つのバージョンがあります。

1. https://haveibeenpwned.com/API/v1
2. https://haveibeenpwned.com/API/v3

方法

RESTベースのAPIは、ソースコード内に定義された特定のメソッドを介して操作されるように設計されています。これらのメソッドは、使用される型とAPIに送信されるデータに応じて異なる応答を返します。APIを操作する際によく使用される一般的なメソッドを以下の表に示します。

方法	用語の説明	説明
得る	取得または読み取り	GETメソッドはAPIから情報を取得するために使用されます
役職	作成または追加または呼び出し	POSTメソッドは、データを作成または追加したり、アクションを呼び出すために使用されます。
置く	パッチまたはアップデート	PUTメソッドはデータを更新したり、何らかの方法で変更したりするために使用されます
消去	破壊または削除	DELETEメソッドは、データを削除したり、アクションを停止したりするために使用されます。

最もよく使われるメソッドはGETとPOSTです。APIの種類（RESTまたはSOAP）やサービスによっては、APIリクエストのヘッダーに追加情報を指定する必要がある場合があります。.

通常、GETリクエストでは、エンドポイント（URL上のパス）にHTTPリクエストを送信し、APIから特定の情報を取得します。例えば、架空の脅威インテリジェンスサービスに次のようなエンドポイントがあるとします。 ip このエンドポイントにIPアドレスを指定する必要があります。このエンドポイントは次のようになります。 /ip/123.123.123.123, これをルート URL に追加します。 https://joshsthreatintel.example/v1/ip/123.123.123.123.

リクエストの一部として、このエンドポイントへの呼び出しで、 得る 要求では、IP アドレス 123.123.123.123 に関する情報が必要です。.

Python と PowerShell Core でこれを行う 2 つの例を次に示します。

• パイソン:
  • 輸入リクエスト
  • レスポンス = リクエスト.get('https://joshsthreatintel.example/v1/ip/123.123.123.123')
• パワーシェル:

   

  • $response = Invoke-RestMethod -Uri '‘https://joshsthreatintel.example/v1/ip/123.123.123.123’' -メソッド GET

別のエンドポイントが利用可能になる場合があります。 役職 架空のサービスへの特定のURL（ジョシュの脅威インテリジェンスサービス 悪意のあるアクティビティをスキャンできるようにする。このエンドポイントは URL ルート URL に追加されます: https://joshsthreatintel.example/v1/url.

通常のhttpリクエストに加えて、この偽のサービスに投稿してURLをスキャンする場合は、 体 リクエストのURL ジョシュの脅威インテリジェンスサービス スキャンする。Pythonでの例は次の通り。

インポートリクエスト body = { 'url': 'http://some.malicious.website.com' } レスポンス = requests.post('https://joshsthreatintel.example/v1/url', data=body}

上記の例は一般的であり、ほとんどのAPIで推奨されていますが、このエンドポイントでは次のようなことも可能です。 得る クエリパラメータを使用した URL。.

クエリパラメータは、基本的にAPIから情報をフィルタリングまたは選択する方法です。クエリパラメータは、サービスがユーザーにAPI呼び出しから返される結果に影響を与えることを許可している場合によく使用されますが、HTTPリクエストの本文に属性を指定する代わりにURLをスキャンするなど、アクションを呼び出すために使用することもできます。.

クエリパラメータは通常、互いに追加されるため、可読性が低下します（個人的な意見です）。以下は、APIでクエリパラメータを使用する際に見られる例です。

https://joshsthreatintel.example/v1/url?url=some.malicious.website.com {API へのウェブサイト パス}/{エンドポイント}?{param=値}

上記の例からわかるように、APIのルートパスとエンドポイントがあります。 URL この場合。 URL エンドポイントにクエリパラメータが表示されます。クエリパラメータは ? その後にパラメータ名と、そのパラメータに使用する値が続きます。.

APIエンドポイントでは、複数のクエリパラメータを指定できる場合があります。例えば、RIPE（Réseaux IP Européens）のREST APIから特定のIPアドレスの情報を取得するためのURL構文は次のとおりです。

https://rest.db.ripe.net/search?source=ripe&query-string={querystring} {API へのウェブサイト パス}/{エンドポイント}?{param=value}&{param=value}

追加されたことに気づいたかもしれません ＆、, これは、別のクエリパラメータがあることを示しています。これには、パラメータ名と、このパラメータに使用する値も含まれています。APIでは、これらのパラメータを複数連結して使用できる場合があります。特定のエンドポイントで何が許可されているかについては、APIドキュメントをご確認ください。.

実際の API では、クエリ パラメータを使用するか、リクエストの本文にデータのキーと値のペアを提供する必要があることがわかります。.

ヘッダー

APIを使用する場合、 得る または 役職 または別の方法で ヘッダー HTTPリクエストの。これは認証トークン、コンテンツタイプの指定、またはその他の情報の提供などです。.

基本的には、 ヘッダ 値はAPIとの接続を確立するために使用されるメタデータです。このメタデータは、APIが実行するアクション/リクエストの種類に応じて認証または環境設定を行うために使用されます。.

認証を必要とするAPIでは、HTTPリクエストヘッダーにトークンを提供することが求められることが非常に一般的です。このトークンは長期的なトークンである場合もあれば、委任ベースの認証スキーム（OAuth2など）の場合は一定期間ごとに更新する必要がある一時的なトークンである場合もあります。いずれにせよ、この認証を提供することはAPIにとって一般的です。.

また、以下の指定も必要になる場合があります。 受け入れる または コンテンツタイプ ヘッダーと 承認 ヘッダー。簡単に言えば、ヘッダーは通常、キーと値のペアの形式をとります。以下は、Pythonでこれらの2つのヘッダーがどのようになるかを示した例です。

custom_headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {SOME_AUTHENTICATION_TOKEN}' }

これらのヘッダーは、HTTPリクエストとともにサーバーに送信されます。APIの使用時にはヘッダーが必須の場合とそうでない場合があります。APIでヘッダーが必須の場合、通常はHTTPリクエストで使用されるすべてのメソッドでヘッダーが必要になります。.

REST APIの基礎を理解する上で、この記事がお役に立てば幸いです。次の投稿では、REST APIよりもはるかに複雑なSOAP（Simple Object Access Protocol）APIについて詳しく解説します。.