はじめに
初めまして。昨年11月にイメージ・マジックに入社しました堀田です。
今年は急に寒くなりましたね。秋を通り越して一気に冬になってしまったように感じます。
今年は急に寒くなりましたね。秋を通り越して一気に冬になってしまったように感じます。
イメージ・マジックでは外部から注文情報を取り込み、生産システムと連携する機能を開発する場面があります。最近その中で、外部APIを呼び出して画像データを取得するプログラムを実装する機会がありました。「外部APIを叩く」というと、なんとなくURLを呼び出して結果を受け取るだけ、というイメージを持たれがちですが、実際にはもう少し押さえておくべきポイントがありましたので共有したいと思います。
外部APIを呼び出す際の実装ポイント
私の整理では大きく5つです。- エンドポイント（URL）とHTTPメソッド
- 認証方式
- HTTPヘッダーに含める情報（例: トークン、Content-Type）
- リクエストボディの形式・項目
- レスポンス（戻り値JSONなど）の構造
エンドポイント（URL）とHTTPメソッド
まずエンドポイントですが、これはリクエスト先のURLそのものです。HTTPメソッドについては、よく使われるのはGETとPOSTです。今回は画像取得APIでしたが、メソッドはPOSTでした。取得系のAPIをPOSTで呼ぶことに違和感を持つ方もいるかもしれません。
ただ、秘匿性の高い情報を扱う場合には、GETではなくPOSTを使うことは珍しくありません。 理由のひとつは、GETだとパラメータがクエリ文字列としてURLに露出するため、ブラウザの履歴やサーバのアクセスログなどに残りやすいことです。POSTでボディ側に載せる設計にすることで、少なくともURLとしては表に出なくなります。もちろん、POSTにしたから自動的に安全になるわけではありませんが、現実的なリスクを下げる手段のひとつにはなります。 もうひとつの理由は、リクエスト内容が複雑な場合です。検索条件などが増えていくとクエリ文字列が長くなりすぎてしまうことがあります。その場合、あえてPOSTで設計することがあります。実際、社内の検索機能でもPOSTにしているケースがあります。
認証方式
次に、認証方式についてです。外部APIでは、誰でも呼び出せてしまうと困るので、基本的には何らかの認証・認可の仕組みを要求されます。代表的な方式としては次のようなものがあります。- Basic認証
- Digest認証
- Bearerトークン認証
- JWT（JSON Web Token）
- OAuth 2.0
- HMAC認証
今回扱ったAPIでは、外部のシステムに対して安全にリクエストを送ることが重要だったため、認証や署名まわりの仕様を正しく理解することが必要でした。
レスポンス（戻り値JSONなど）の構造
最後にレスポンスについてです。今回は画像データになりますが、画像データはどのように取得できるのでしょうか。正直なところ、最初は自分も「png や jpeg といった拡張子付きのファイル名のようなもの、もしくはそのURLが返ってくるのかな」と漠然と考えていました。しかし、実際の仕様書を見るとレスポンスは「バイナリデータ」と記載されています。これはつまり、画像ファイルそのものの中身（=画像本体のバイト列）をレスポンスボディとして直接返してくる、という意味です。よく考えるとこれは当たり前で、サーバ側はただ「ファイル名っぽい文字列」だけを返すだけではクライアントに画像を渡せません。サーバは画像の元データであるバイナリデータそのものを返却し、それをクライアント側がファイルとして保存することで、はじめてPNGやJPEGとして扱えるわけです。実装としては、レスポンスヘッダーの Content-Type（例: image/png, image/jpeg）を見て、どの拡張子で保存するか判断するイメージになります。