APIとRESTの基礎

この単元で学ぶこと

APIは、ソフトウェアやサービスが決められた方法で機能やデータを利用できるようにする窓口です。ネットワーク運用では、機器やコントローラの状態取得、設定変更、監視データの収集などにAPIを利用できます。

この単元では、API、REST、リソース、URI、エンドポイント、HTTPメソッド、HTTPステータスコード、リクエストとレスポンスの基本を学びます。

APIとは

APIは、アプリケーションやサービスが外部から機能やデータを利用するための決められた接点です。

人が画面やCLIで操作する代わりに、プログラムがAPIへリクエストを送り、結果を受け取ることで、状態確認や設定変更を自動化できます。

RESTとは

RESTは、Webの仕組みを利用してリソースを扱うための設計上の考え方です。多くのREST APIでは、URIで対象を識別し、HTTPメソッドで行いたい操作を表します。

REST APIは、HTTPを使うAPIすべてを指す言葉ではありません。実際のAPI仕様を確認し、利用できるURI、メソッド、認証、データ形式、制約を理解して利用します。

リソースとURI

リソースは、APIで扱う対象です。ネットワーク運用では、機器、インターフェース、VLAN、ユーザー、設定、統計情報などがリソースになることがあります。

URIは、リソースを識別するための文字列です。たとえば、特定の機器やインターフェースを表すURIへリクエストを送ることで、対象を指定します。

エンドポイント

エンドポイントは、APIへアクセスするための具体的なURIです。APIドキュメントでは、エンドポイントごとに利用できるHTTPメソッド、必要なパラメータ、返されるデータ形式、権限などが説明されます。

同じAPIでも、読み取り専用のエンドポイントと、設定変更を行うエンドポイントでは、必要な権限や影響が異なります。

HTTPメソッド

HTTPメソッドは、対象リソースに対して行いたい操作の意味を表します。代表的なものにGET、POST、PUT、DELETEがあります。

GETは現在の表現を取得するために使われます。POSTは対象リソース側の処理を依頼する用途に使われます。PUTは指定したリソースの状態を作成または置き換える意図で使われ、DELETEは対象リソースの削除を依頼します。

リクエストとレスポンス

APIクライアントは、URI、HTTPメソッド、ヘッダー、必要に応じて本文を含むリクエストを送ります。APIサーバーは、処理結果をHTTPステータスコード、ヘッダー、本文を含むレスポンスとして返します。

本文にはJSON形式のデータが使われることが多いため、APIとJSONはセットで学ぶと理解しやすくなります。

HTTPステータスコード

HTTPステータスコードは、リクエスト処理の結果を表す番号です。たとえば、2xxは成功、4xxはリクエスト側の問題、5xxはサーバー側の問題を示す分類です。

APIを利用するときは、本文だけではなく、ステータスコード、エラー内容、リクエストIDなどを確認し、失敗の原因を切り分けます。

API利用時の注意

設定変更を行うAPIでは、認証情報やトークンの扱い、必要最小限の権限、HTTPSの利用、対象確認、実行ログ、ロールバック方法を考えます。

まずはGETなどの読み取り操作でデータ取得を試し、APIドキュメントの例と実際のレスポンスを確認してから、変更操作へ進みます。

まず覚えたいポイント

APIはプログラムが機能やデータを利用するための窓口です。REST APIでは、URIでリソースを指定し、HTTPメソッドとリクエストで操作を表し、レスポンスとステータスコードで結果を確認します。