ゆめさくコード

はじめてのREST API

luagate/rest-api-introREST API入門21 枚Web 開発
スライド103触れる図解124レッスンの導入6

上から下へ、全 21 枚そのまま並べています。

発表モードで開く

REST API入門

はじめてのREST API

Webアプリ同士が会話するしくみを2時間で理解する

1
1

目次

今日の流れ

1. APIってなに？ — まずはイメージから

2. HTTPのおさらい — メソッドとステータス

3. REST設計の考え方 — きれいなURLとは

4. ライブデモ — 実際にAPIを叩いてみる

5. まとめと振り返り

2
2
REST API入門 - APIとは

APIとは

プログラム同士がやり取りするための「窓口」のことです。

API（エーピーアイ / Application Programming Interface）

あるソフトウェアの機能やデータを、別のソフトウェアから使えるように公開した「決められた使い方の窓口」。

・人間ではなくプログラムが使う窓口

・「こう頼めば、こう返ってくる」という約束ごと

・中身のしくみを知らなくても利用できる

・REST APIはWebでよく使われるAPIの形式の一つ

11
3
REST API入門 - APIとは

API = レストランの注文に似ている

APIの役割は、レストランのウェイターにたとえると分かりやすいです。

あなた（客）
  • アプリやブラウザ
  • 「これがほしい」と注文する
ウェイター（API）
  • 注文を厨房に伝える
  • 料理を運んでくる
  • 決まった頼み方がある
厨房（サーバー）
  • データを保管・処理
  • 客とは直接話さない
  • ウェイター経由で応える
12
4
REST API入門 - APIとは

Webアプリが動くときの流れ

私たちがアプリを使うとき、裏ではこんなやり取りが起きています。

1. リクエスト

アプリが「天気を教えて」とAPIにお願いを送る

2. 処理

サーバーがデータベースから今日の天気を探す

3. レスポンス

「晴れ・25度」というデータをアプリに返す

4. 表示

アプリが受け取ったデータを画面に表示する

13
5
REST API入門 - APIとは

実は身近にあるAPI

普段使っているサービスの多くが、裏でAPIを呼び出しています。

裏で呼ばれているAPIの例

地図アプリで現在地を表示

地図サービスのAPIで地図データを取得

通販サイトで決済

決済サービスのAPIでクレジット処理

アプリにSNSログイン

SNSのAPIで本人確認

天気予報ウィジェット

天気サービスのAPIで予報を取得

14
6
REST API入門 - HTTPのおさらい

HTTPのおさらい

既に学んだメソッドとステータスコードを、1枚でサッと復習します。

やること
例
ステータスの目安

GET

取得する

記事一覧を見る

200 OK

POST

新しく作る

記事を投稿する

201 Created

PUT

まるごと更新

記事を書き直す

200 OK

DELETE

削除する

記事を消す

200 / 204

21
7
REST API入門 - REST設計

RESTとは

Web APIを分かりやすく作るための「設計のお作法」です。

REST（レスト）

データを「リソース（資源）」として捉え、URLで名前をつけ、HTTPメソッドで操作するという考え方。この作法に沿ったAPIをREST APIと呼ぶ。

・リソース = 扱いたいデータのまとまり（たとえばユーザーや記事）

・URLはリソースの「住所」

・操作はメソッドで表す（URLには動詞を入れない）

31
8
REST API入門 - REST設計

URLの設計 — 悪い例と良い例

・RESTでは「URLは名詞、操作はメソッド」が基本です。

イマイチなURL

  • /getUser?id=1
  • /createUserNow
  • /deleteUserById?id=1
  • 動詞がURLに入っている
  • 操作ごとにURLが増える

RESTらしいURL

  • GET /users/1
  • POST /users
  • DELETE /users/1
  • URLは名詞（リソース）だけ
  • 操作はメソッドで表す
32
9
REST API入門 - REST設計

リソース指向のURL早見表

「users」というリソースへの操作を、URLとメソッドの組み合わせで表します。

メソッド
URL

ユーザー一覧を取得

GET

/users

特定のユーザーを取得

GET

/users/1

ユーザーを新規作成

POST

/users

ユーザー情報を更新

PUT

/users/1

ユーザーを削除

DELETE

/users/1

33
10
REST API入門 - REST設計

PUT と PATCH のちがい

どちらも「更新」ですが、送る範囲が違います。実務でよく迷うポイントです。

PUT（まるごと差し替え）

  • リソース全体を送り直す
  • 送らなかった項目は消える/初期値に
  • 「この内容で上書きして」
  • 例 名前もメールも全部入れて送る

PATCH（一部だけ更新）

  • 変えたい項目だけ送る
  • 送らなかった項目はそのまま
  • 「ここだけ直して」
  • 例 メールアドレスだけ送る
34
11
REST API入門 - REST設計

POSTだけで済ませるケースもある

現実にはPUT/PATCH/DELETEを使わず、POSTに寄せる設計もよくあります。

HTMLフォームの制約
  • ブラウザのフォームはGETとPOSTのみ
  • PUT/DELETEが素直に使えない
  • _methodなどで擬似的に表現することも
操作を動詞で表したい
  • 「メール送信」「再起動」など
  • 名詞のリソースに収まりにくい
  • POST /jobs/123/restart のように送る
GraphQL / RPC風
  • すべてPOSTの1エンドポイント
  • 本文の中身でやることを指定
  • RESTとは別の設計思想
345
12
REST API入門 - REST設計

JSONってこんな形

・「名前と値」の組み合わせでデータを表します。人もプログラムも読めます。

json
{
  "id": 1,
  "name": "田中 太郎",
  "email": "taro@example.com",
  "isActive": true,
  "tags": ["admin", "editor"]
}
35
13

REST API入門 - ライブデモ

4

第4部 ライブデモ

実際にAPIを叩いてみよう

40
14
REST API入門 - ライブデモ

今日のデモ相手「PokéAPI」

ポケモンのデータを返してくれる、無料・登録不要の公開APIです。

PokéAPI（pokeapi.co）

ポケモンの名前・タイプ・とくせいなどをJSONで返してくれるREST API。誰でも自由に、登録なしでGETできる学習に最適なAPI。

・認証もAPIキーも不要

・ブラウザでURLを開くだけでも結果が見られる

・読み取り専用（GETのみ）

・https://pokeapi.co/api/v2/ から始まる

41
15
REST API入門 - ライブデモ

デモ1 ポケモンを取得する

・URLを叩くだけでポケモンのデータがJSONで返ってきます。

bash
# メタモン（ditto）の情報を取得する
curl https://pokeapi.co/api/v2/pokemon/ditto

# 返ってくるJSON（一部を抜粋）
# {
#   "id": 132,
#   "name": "ditto",
#   "height": 3,
#   "weight": 40,
#   "types": [{ "type": { "name": "normal" } }]
# }
42
16
REST API入門 - ライブデモ

デモ2 URLを変えれば別のデータ

・URLは「住所」。末尾を変えるだけで、別のリソースが取れます。ブラウザでも開けます。

bash
# ピカチュウに変えてみる
curl https://pokeapi.co/api/v2/pokemon/pikachu

# 「タイプ」というリソースを取る（ID指定）
curl https://pokeapi.co/api/v2/type/3

# 一覧をまとめて取る（件数と開始位置を指定）
curl "https://pokeapi.co/api/v2/pokemon?limit=10&offset=0"
43
17
REST API入門 - ライブデモ

デモ3 POSTで作成する

・PokéAPIは読み取り専用なので、書き込みは練習用APIで試します。-XでPOST、-dでデータを送ります。

bash
# 新しい記事を作成する（jsonplaceholderは書き込みも試せる練習用API）
curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "はじめてのAPI", "body": "投稿テスト", "userId": 1}'

# 返ってくるレスポンス（例）→ 作られたデータにidが付く
# { "title": "はじめてのAPI", "body": "投稿テスト", "userId": 1, "id": 101 }
44
18
REST API入門 - まとめ
クイズ

振り返りクイズ

今日の内容を確認しましょう。

GET /users/5 というリクエストの意味として正しいものは？

A
5人のユーザーを新規作成する
B
IDが5のユーザー情報を取得する
C
ユーザーを5人削除する
D
usersページに移動するだけ
52
19
REST API入門 - まとめ
答え

振り返りクイズ 解答

GET /users/5 というリクエストの意味として正しいものは？

A
5人のユーザーを新規作成する
B
IDが5のユーザー情報を取得する
C
ユーザーを5人削除する
D
usersページに移動するだけ

GETは取得、/users/5 は「usersリソースのうちIDが5のもの」を指す住所です。つまり「IDが5のユーザーを取得する」が正解です。

53
20
"

APIは「決められた頼み方で、欲しいデータをもらう窓口」。URLで相手を指し、メソッドでやりたいことを伝える。この感覚さえつかめば、世界中のサービスとつながれます。

— REST API入門

55
21