APIとは何か

APIは Application Programming Interface の略です。

人がネットワーク機器を操作する場合、 SSHでログインしてCLIコマンドを入力する方法があります。

一方、プログラムから同じような操作をするときに、 人間向けのCLI画面を操作するのではなく、 プログラム向けに用意された入口を利用できる場合があります。 その入口がAPIです。

REST APIとは何か

RESTは Representational State Transfer の略で、Webのような分散システムを設計するための アーキテクチャスタイルです。

実務で「REST API」と呼ばれるAPIでは、 HTTPを利用してリソースを指定し、 GETやPOSTなどのHTTPメソッドを使って 情報取得や操作を行う構成が広く使われています。

リソースをURLで表す

APIでは、操作したい対象をURLで表します。 この対象をリソースと考えます。

https://api.example.local/api/v1/devices

この例では、devicesというリソースを表しています。

特定の機器を指定するAPIであれば、次のような形式になる場合があります。

https://api.example.local/api/v1/devices/1001

REST APIの通信の流れ

REST APIでは、基本的に クライアントがリクエストを送り、 APIサーバーがレスポンスを返す という流れになります。

1. クライアントがAPIのURLを指定する どのリソースを操作するのか決めます。
2. HTTPメソッドを決める 情報取得ならGET、作成ならPOSTなど、 目的に合わせたメソッドを使用します。
3. 必要なヘッダーや認証情報を付ける APIキーやトークンなどが必要になる場合があります。
4. 必要に応じてデータを送信する 設定変更などではJSON形式のデータを送信することがあります。
5. サーバーがレスポンスを返す HTTPステータスコードやデータを確認し、 処理が成功したか判断します。

APIリクエストを構成する要素

REST APIを利用するときは、 主に次の4つを確認します。

APIリクエストのイメージ

POST /api/v1/devices HTTP/1.1
Host: api.example.local
Authorization: Bearer <token>
Content-Type: application/json

{
  "hostname": "RTR-01",
  "ip_address": "192.0.2.10"
}

この例では、APIサーバーへ 「RTR-01という機器情報を登録してください」 という内容を送信しているイメージです。

HTTPメソッドの基本

REST APIを読むうえで、 GET・POST・PUT・DELETEなどのHTTPメソッドは重要です。

HTTPステータスコードを確認する

APIを実行した後は、 返ってきたデータだけでなく HTTPステータスコード を確認します。

400番台と500番台を分けて考える

トラブルシューティングでは、 ステータスコードの分類を見ると確認方向を整理できます。

• 2xx：正常処理された可能性が高い
• 4xx：リクエスト・認証・権限・URLなどクライアント側を確認する
• 5xx：APIサーバー側でエラーが発生している可能性を確認する

JSONとREST API

REST APIでは、 リクエストやレスポンスのデータとして JSONがよく利用されます。

たとえば、ネットワーク機器の情報取得結果が 次のように返ってくる場合があります。

{
  "hostname": "RTR-01",
  "management_ip": "192.0.2.10",
  "status": "up"
}

CLIでは人が読みやすい文字列として表示されますが、 APIではプログラムが処理しやすい構造化データとして取得できることがあります。

JSONの具体的な構造や読み方は、 次回「JSON・YAMLの読み方」 で詳しく解説します。

APIの認証

ネットワーク機器や管理システムのAPIを、 誰でも自由に実行できる状態にはできません。

そのため、多くのAPIでは何らかの認証・認可が必要です。

ネットワークでREST APIを使う場面

ネットワークエンジニアがREST APIを使う目的は、 「APIを使うこと」そのものではありません。

人が繰り返している情報取得や設定処理を、 プログラムから再現できるようにすることが目的です。

100台の装置情報を集める場合

人が100台へSSH接続し、showコマンドを入力して、 Excelへ転記する方法では時間がかかります。

APIが利用できるシステムであれば、 PythonなどからAPIを繰り返し呼び出し、 必要なデータをまとめて取得できる可能性があります。

curlでAPIを実行するイメージ

APIの動作確認では、 curlを使ってHTTPリクエストを送る方法があります。

たとえば、次のコマンドは架空のAPIから 機器一覧を取得するイメージです。

curl -X GET \
  "https://api.example.local/api/v1/devices" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

要素を分解すると、次のようになります。

PythonからREST APIを利用するイメージ

Pythonでは、HTTPリクエストを扱うライブラリを使うことで、 APIアクセスをプログラムへ組み込めます。

以下は処理イメージです。

import requests

url = "https://api.example.local/api/v1/devices"

headers = {
    "Authorization": "Bearer <token>",
    "Accept": "application/json"
}

response = requests.get(
    url,
    headers=headers,
    timeout=10
)

print(response.status_code)

if response.status_code == 200:
    data = response.json()
    print(data)

重要なのはコードを暗記することではありません。

1. URLを指定する
2. 認証情報などのヘッダーを作る
3. GETリクエストを送る
4. ステータスコードを確認する
5. レスポンスデータを処理する

という流れを理解してください。

REST APIとRESTCONF

ネットワーク自動化を学んでいると、 RESTCONFという言葉を見ることがあります。

RESTCONFは、 YANGで定義されたネットワーク管理データへ HTTPベースでアクセスするためのプロトコルです。

Cisco IOS XEなど、 プログラマビリティを備えたネットワークOSでは、 CLI以外にNETCONFやRESTCONFなどを利用できる環境があります。

REST APIでよくある失敗

顧客・上司へREST APIをどう説明するか

技術に詳しくない相手へ 「REST」「HTTPメソッド」「JSON」と説明しても、 API導入の価値は伝わりにくい場合があります。

説明例

技術を業務効果へ変換する

上級エンジニアには、 「APIを使えます」だけでなく、 APIによってどの作業を減らし、 どのリスクを低減できるのか を説明する力が求められます。

REST APIで使われる英語表現

よく使われる単語

APIドキュメントでよく見る表現

自分の言葉で説明する課題

後輩エンジニアから、 「SSHでコマンドを取れるなら、APIを使う意味は何ですか？」 と質問されました。

1分程度で説明してください。