レスポンス圧縮

VulnCheck APIは、圧縮を要求するすべてのクライアントに対してレスポンスを圧縮して返します。JSONは非常によく圧縮されるため、圧縮後のレスポンスは通常、元のサイズのごく一部になります。ダウンロードが速くなり、帯域幅の使用量が減り、データの内容は変わりません。

圧縮は、v3およびv4 API、NVD互換エンドポイントを含む、api.vulncheck.com上のすべてのエンドポイントに適用されます。

圧縮のメリット

レスポンスが大きいほど効果も大きくなります。vulncheck-nvd2などのインデックスをページングで取得する場合や、連携システムから定期的にAPIをポーリングする場合、圧縮によって転送データ量が1桁削減されます。

/v3/index/vulncheck-nvd2のデフォルトページを転送時のサイズで測定した結果:

実際の削減率はエンドポイントやページサイズによって異なります。ページが大きいほど圧縮効率が高く、特にBrotliで顕著です。

これにより、次のようなメリットがあります:

• レスポンスの高速化 - 特に低速、長距離、または混雑した回線で効果があります。
• 帯域幅の削減 - 従量課金の回線、プロキシ、またはデータ転送量に課金されるクラウドNATゲートウェイを経由する場合に重要です。
• 一括取得の高速化 - 大きなインデックスをページングで取得する際、各ページのダウンロードが速くなります。
• データは変わりません - 解凍後のレスポンスは、非圧縮版とバイト単位で同一です。圧縮によってレート制限が変わることはなく、追加のリクエストとしてカウントされることもありません。

仕組み

圧縮は標準的なHTTPコンテントネゴシエーションに従います:

1. クライアントは、デコード可能なエンコーディングをAccept-Encodingリクエストヘッダーで提示します。
2. APIはその中から1つを選んで本文を圧縮し、選択したエンコーディングをContent-Encodingレスポンスヘッダーで示します。
3. クライアントは本文を解凍してからコードに渡します。

APIはBrotli (br) とgzipをサポートしています。クライアントが両方を受け入れる場合はBrotliが使用されます。リクエストにAccept-Encodingヘッダーがない場合、またはAPIがサポートしていないエンコーディングのみが指定されている場合、レスポンスはこれまでどおり非圧縮で送信されます。圧縮を要求しないクライアントは、変更なしでそのまま動作します。

レスポンスにはVary: Accept-Encodingも含まれるため、キャッシュやプロキシは圧縮版と非圧縮版を区別して保持します。

何か変更する必要はありますか?

ほとんどのクライアントはすでに圧縮を要求し、自動的にデコードしているため、多くの場合すでにメリットを得ています。

curlを使用する場合や、リクエストを手動で組み立てるスクリプトの場合は、--compressedを追加するか、Accept-Encodingヘッダーを自分で設定してください。

curl --compressed \
  --url https://api.vulncheck.com/v3/index/vulncheck-nvd2 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer insert_token_here'

// Goのデフォルトのトランスポートはgzipを要求し、本文を自動的に解凍します。
// Accept-Encodingを自分で設定しないでください。設定すると自動解凍が
// 行われなくなり、本文を自分のコードでデコードする必要があります。
request, _ := http.NewRequest("GET", "https://api.vulncheck.com/v3/index/vulncheck-nvd2", nil)
request.Header.Set("Accept", "application/json")
request.Header.Set("Authorization", "Bearer insert_token_here")

response, _ := http.DefaultClient.Do(request)
defer response.Body.Close()

# requestsはデフォルトでgzipを要求し、brotliパッケージがインストールされていれば
# (pip install brotli) Brotliも要求します。解凍は自動的に行われます。
import requests

url = "https://api.vulncheck.com/v3/index/vulncheck-nvd2"
headers = {
  "accept": "application/json",
  "authorization": "Bearer insert_token_here"
}

response = requests.get(url, headers=headers)
print(response.headers.get("Content-Encoding"))  # br または gzip
print(response.json())

圧縮が有効か確認する

レスポンスヘッダーのみを出力し、content-encodingを確認します:

curl --silent --output /dev/null --dump-header - \
  --header 'Accept-Encoding: br, gzip' \
  --header 'Authorization: Bearer insert_token_here' \
  https://api.vulncheck.com/v3/index/vulncheck-kev

HTTP/2 200
content-type: application/json
content-length: 37012
content-encoding: br
vary: Origin,Accept-Encoding

content-encodingヘッダーがない場合、リクエストでサポートされているエンコーディングが提示されていません。クライアントがAccept-Encoding: brまたはAccept-Encoding: gzipを送信しているか確認してください。

オフラインバックアップ

オフラインバックアップはすでに圧縮済みのzipアーカイブとしてダウンロードされます。バックアップの一覧とダウンロードリンクを返す/v3/backupエンドポイントのJSONは、他のAPIレスポンスと同様に圧縮されます。データセット全体が必要な場合は、引き続きバックアップが最も効率的な方法です。数百回のページングリクエストではなく、1回のダウンロードで済みます。