REST API、
結局何を送って
何が返ってくる？

APIという言葉は、 開発の中でかなりの頻度で出てきました。

でも最初は、 「APIを呼ぶ」 と言われても、 実際に何が飛んでいるのか あまりイメージできていませんでした。

URLがある。

JSONがある。

何か送っている。

返ってきた値を使っている。

最初はそれぞれ別のものに見えていました。

相手にRequestを送り、
Responseを受け取る。

かなり大きく見ると、 まずはこの往復です。

そこから、 「Requestの中に何がある？」 「Responseのどこを見る？」 と分けていくと、 少しずつ追いやすくなりました。

最初は、 APIで送るものといえば JSONくらいのイメージでした。

でも実際にRequestを見ると、 いくつかの情報が組み合わさっています。

• URL
• HTTPメソッド
• Header
• Body

例えば、 ユーザー情報を登録するAPIなら こんなRequestになります。

POST /users

Content-Type: application/json

{
    "name": "Taro",
    "age": 30
}

POST がHTTPメソッド。

/users が送信先。

Content-Type はHeader。

JSON部分がBodyです。

全部まとめて 「APIに送るデータ」 と見るより、 役割ごとに分けた方が かなり分かりやすくなりました。

API仕様を見ると、 GET や POST が 当たり前のように書かれています。

最初は、 「GETは取る、POSTは送る」 くらいの認識でした。

実際に見ていくと、 HTTPメソッドは そのURLに対して何をしたいのか を表していました。

• GET：データを取りたい
• POST：新しく登録したい
• PUT / PATCH：今あるものを更新したい
• DELETE：削除したい

例えば、 同じ /users でも、 メソッドが違えば意味が変わります。

GET  /users
POST /users

上は取得。

下は登録。

API仕様を見るときに、 URLだけじゃなく HTTPメソッドも一緒に見る。

これだけでも、 何をするAPIなのか かなり追いやすくなりました。

APIのテストでは、 Postmanも使っていました。

Postmanは、 APIを直接呼び出して RequestとResponseを確認できるツールです。

URLを入れる。

GETやPOSTを選ぶ。

Headerを設定する。

必要なら認証情報を入れる。

BodyにJSONを入れる。

送信すると、 Status CodeやResponse Bodyが返ってきます。

Headerや認証情報があること自体は、 Postmanを使っていれば 画面上で普通に見えていました。

自分の中でつながったのは、 実装したコードと Postman上の項目を見比べたときです。

「コードで設定しているこれが、
Postmanのここに入るのね」

実装する。

Postmanでテストする。

もう一度コードを見る。

その繰り返しで、 Requestの構造と コード上の処理が 少しずつ一致してきました。

Postmanを使った API単体のテストや切り分けは、 別の記事でもう少し掘ります。

Postmanでは、 HeaderとBodyの入力欄が 分かれていました。

それを実装側のコードと見比べると、 「この設定がHeaderで、 このデータがBodyなのか」 と対応して見えてきます。

Content-Type: application/json
Authorization: Bearer xxxxxxxx

Content-Type は、 Bodyが何の形式なのかを表す情報。

認証が必要なAPIなら、 Authorizationなども Headerに入ることがあります。

一方でBodyには、 実際に相手へ渡したいデータを入れます。

{
    "name": "Taro",
    "age": 30
}

画面上ではPostmanの別々の欄。

コード上では、 Headerを設定して、 Bodyを作って、 Requestを送る。

この対応が見えるようになってから、 APIのコードもかなり追いやすくなりました。

APIを触ると、 JSONはかなりの頻度で出てきます。

{
    "name": "Taro",
    "age": 30
}

最初は、 「波括弧で囲まれたデータ」 くらいに見えていました。

ざっくり見るなら、 項目名（key）と値（value）を セットで持つデータ形式 です。

上の例なら、 name がkeyで Taro がvalue。

age がkeyで 30 がvalueです。

値の中に、 さらにオブジェクトや配列を 持つこともできます。

{
    "name": "Taro",
    "skills": [
        "Java",
        "SQL"
    ],
    "company": {
        "name": "Sample Company",
        "department": "System"
    }
}

APIでは、 こうしたJSONを Requestとして送ったり、 Responseとして受け取ったりします。

だから、 「どんなJSONを送るのか」 「どんなJSONが返るのか」 はAPI仕様を見るうえでも重要でした。

Requestを送ると、 相手側で処理されて Responseが返ってきます。

PostmanでAPIを叩いたときも、 送ったRequestだけではなく 返ってきたResponseを確認します。

• Status Code
• Header
• Body

HTTP/1.1 200 OK
Content-Type: application/json

{
    "result": "success"
}

Bodyにどんな値が返ってきたか。

Status Codeはいくつか。

Requestを送るところだけではなく、 Responseまで一緒に見ることで 一つの通信として見えるようになりました。

APIがうまく動かなかったとき、 ResponseのStatus Codeは 最初に見る情報の一つでした。

• 200系：正常に処理できた
• 400系：Requestや認証など、呼び出し側も確認する
• 500系：サーバー側の処理も確認する

例えば、 404 なら URLや対象が合っているかを見る。

401 や 403 なら、 認証や権限を見る。

500 が返ってきたなら、 サーバー側で何か起きていないかを見る。

Status Codeだけで 原因が全部分かるわけではありません。

でも、 「何が返ってきた？」 を見ることで、 次に確認する場所をかなり絞れます。

自分が触っていたJava・Springでは、 Request BodyのJSONを Javaのオブジェクトとして受け取る形もありました。

@PostMapping("/users")
public ResponseEntity<String> createUser(
        @RequestBody UserRequest request) {

    String name = request.getName();

    return ResponseEntity.ok("received");
}

Postmanでは、 BodyにJSONを入れて送る。

Spring側では、 @RequestBody で その内容を受け取る。

Javaの処理では、 オブジェクトになった値を getterで取り出す。

ここでも、

「Postmanで入れていたこのデータが、
コードではここに来るのね」

と対応して見えるようになりました。

Java・Springは REST APIそのものではなく、 自分が触った実装方法の一つです。

ただ、 実装とPostmanでの確認を行き来したことで、 APIの通信とコードの処理が 自分の中で一致していきました。

APIが動かないとき、 コードだけを見ても 原因が分からないことがあります。

そういうときは、 RequestとResponseを 一つずつ分けて確認します。

• URLは合っているか
• HTTPメソッドは合っているか
• Headerは合っているか
• 認証情報は合っているか
• JSONのkeyは合っているか
• valueの型は合っているか
• Requestは送れているか
• Status Codeは何か
• Response Bodyには何が入っているか

「動かない」ではなく、
「どこまで動いてる？」

そして、 コードから呼んだときは動かないけど Postmanから直接叩いたら動く、 という差も切り分け材料になります。

APIそのものなのか。

呼び出しているアプリ側なのか。

この辺を切り分けるときにも、 Postmanはかなり使いやすいツールでした。

ここは次の記事で もう少し深く整理します。