皆さん、こんにちは！

普段、API開発やテストの現場で奮闘しているエンジニアの皆さん、ファイルアップロードのテストって、地味にハマりがちじゃないですか？

私も以前、なぜかうまくいかなくて何時間も悩んだ経験があります。あのとき、もし誰かがサッと答えをまとめてくれていたら…と、心から思いました。

そんな個人的な経験も踏まえ、今回は私が普段愛用しているAPIツール「EchoAPI」でのファイルアップロードをテーマに、知っておきたい基本ルールから具体的な手順、そしてハマりどころまで、「これさえ読めば大丈夫！」な実践ガイドをまとめてみました。

教科書的な解説ではなく、実際に手を動かすときに役立つ、現場の知恵をギュッと詰め込んだつもりです。ぜひ、開発のお供にしてもらえたら嬉しいです。

ファイルアップロードの超基本！3つの疑問に答える

まずは、ファイルアップロードテストを行う上で、誰もが一度はぶつかるであろう3つの疑問に、明快にお答えします。

multipart/form-dataを使うべき？
→ はい、これはもう「必須」です。HTTPプロトコルで、ファイルのようなバイナリデータを送信する際の標準的な形式がmultipart/form-dataだからです。テキストデータとバイナリデータを同時に送るのにも最適で、EchoAPIももちろん完全サポートしています。
ファイルを入れるフィールド名（key）は何にすればいい？
→ これはAPIの設計によります。一般的にはfileがよく使われますが、image、document、avatar、upload、videoといった名前もよく見かけます。正解は、必ずAPI仕様書で確認してください。もし自分でAPIを設計する場合は、EchoAPIのインターフェース設計画面で自由に決められます。
ファイル以外の情報（メタデータ）も送るべき？
→ これもAPIの仕様次第ですが、多くの場合、追加情報が必要です。例えば、ファイル名（file_name）やファイルタイプ（media_type）は送信が推奨されます。これらは通常のテキストフィールドとして送信可能です。

補足：こんなメタデータもよくある
ユーザーのアバターをアップロードする例だと、ファイルと合わせて次のような情報も送るケースが多いです。

user_id: 12345（テキストフィールド）
type: "avatar"（テキストフィールド）

重要：とにかく「API公式ドキュメントがすべて」です。これを最優先に確認してください！

EchoAPIでのファイルアップロード、実践ステップ

それでは、実際にEchoAPIを使ってファイルアップロードのテストをする手順を、画像付きで見ていきましょう。

1. インターフェースの準備

APIのメソッドをPOSTに設定します。（仕様書がPUTなどを指定している場合はそれに従います）
「パラメータ追加」をクリックし、新しい行でタイプを「ファイル」**に設定。フィールド名（例：file）を入力します。
Content-Typeをmultipart/form-dataに設定
【超重要！】
Content-Type: multipart/form-dataヘッダーは手動で追加してはいけません！
EchoAPI（やPostmanなどのツール）は、Bodyでform-dataを選択すると、自動でboundary（データの区切り）を含んだ正しいヘッダーを生成してくれるからです。もし手動で追加すると、ヘッダーが重複してエラーになります。自分で追加するのはAuthorization: Bearer <your_token>のような認証情報だけでOKです。
必要に応じて、file_nameやmedia_typeなどのテキストフィールドを追加します。

2. テスト用ファイルのアップロード

ファイルパラメータの行にある「ファイルを選択」をクリック。
ローカルPCから、画像、動画、PDFなどテストしたいファイルを選びます。
もしファイル名やタイプなどのメタデータが必要なら、それらも入力します。

3. リクエストの送信と結果確認

準備ができたら、「送信」ボタンをクリック。
レスポンスエリアに、APIからの結果が表示されます。

すべて正しく設定すると、EchoAPIの画面はこんな感じになります。

Key	Value	Type
`file`	`my_photo.jpg`	File
`user_id`	`12345`	Text

cURLとPostmanでのリクエスト例

普段、これらのツールを使っている方のために、EchoAPIで設定した内容が、他のツールでどう表現されるかを見ておきましょう。

cURL例

ターミナルでサッと試したいときに便利です。

curl --request POST \
  --url http://httpbin.org/anything \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Connection: keep-alive' \
  --header 'User-Agent: EchoapiRuntime/1.1.0' \
  --header 'content-type: multipart/form-data' \
  --form 'file=@[object Object]'

パラメータ解説：

--request POST：HTTPメソッドをPOSTに指定します。
--header：認証情報などをヘッダーに設定します。
--form（-F）：multipart/form-dataのフィールドを指定します。
- 'file=@[object Object]'：fileがフィールド名（key）で、@の後にローカルファイルの絶対パスを指定します。

Postman例

GUIで分かりやすく設定したいときに使います。

HTTPメソッドをPOSTに設定。
URLを入力。
Headersタブで認証情報などを追加。
Bodyタブでform-dataを選択。
以下のキーと値を追加します。
- Key: file、Type: File、Value: ローカルファイルを選択
- Key: file_name、Type: Text、Value: ファイル名
- Key: media_type、Type: Text、Value: MIMEタイプ（例：image/jpeg, application/pdfなど）

😱もしファイルアップロードがうまくいかなかったら…

「あれ、設定は完璧なはずなのに…」そんなときのためのチェックリストです。

APIドキュメントを再確認する：ファイルフィールド名やメタデータが、サーバー側が期待しているものと100%一致していますか？
Content-Typeヘッダー：手動で追加していませんか？ もし追加していたら、削除して再試行しましょう。
Type設定：ファイルフィールドのTypeが「File」に、テキストフィールドのTypeが「Text」になっているか、もう一度確認。
まずはシンプルに：ファイル単体だけでリクエストを送信して、問題なく動作するか確認してみましょう。もし成功すれば、後から追加したメタデータに原因がある可能性が高いです。
エラーメッセージを読もう：失敗したときに返ってくるレスポンスボディには、{"error": "Missing field 'file'"}のように、ヒントとなるエラーメッセージが書かれていることが多いです。面倒でも必ず目を通しましょう。これが解決への一番の近道です。

最後に

いかがでしたか？

ファイルアップロードは、一見複雑そうに見えますが、基本を押さえれば実はシンプルです。EchoAPIを使えば、GUIで直感的に設定できるので、サクッとテストを完了できます。

もしこのガイドが、皆さんの日々の開発での「あれ、うまくいかない…」を少しでも減らすことができたら、筆者としてこれ以上嬉しいことはありません。

もし特定のケースでまた躓いたら、気軽に相談してくださいね。
一緒にベストな解決策を見つけていきましょう！