Skip to content

Latest commit

 

History

History
184 lines (150 loc) · 6.35 KB

oreilly-web-api-the-good-parts.md

File metadata and controls

184 lines (150 loc) · 6.35 KB
Raw
title emoji type topics published
【Oreilly】Web API The Good Parts
🩹
tech
初心者向け
API
Oreilly
true

はじめに

下記の書籍を読みました。 備忘録を書きます。 @card

1. 短く入力しやすいURL

1-1. 必要最低限で表現する

❌ service, apiという言葉があり、一見丁寧なURLだけど、文字数が多くて入力しにくい

https://api.example.com/service/api/search/

⭕ 必要最低限の単語で、文字数が少なく入力しやすい

https://api.example.com/search/

2. 人間が読んで理解できるURL

2-1. 省略系の単語を使わない

❌ sv, uという言葉があるが、意味が伝わりにくい

https://api.example.com/sv/u/

⭕ 省略系を使わず、適切に伝える

https://api.example.com/service/users/

2-2. 単語は英語を使う

❌ 英語: product, スペイン語: productoのように勘違いが発生しにくいように英語にする ❌ ローマ字: seihinは論外

<!-- スペイン語 -->
https://api.example.com/producto/123/
<!-- 日本語 -->
https://api.example.com/seihin/123/

<!-- 英語 -->
https://api.example.com/product/123/

2-3. 適切な英語を使う

❌ find: あるものを探す

https://api.example.com/find/

⭕ search: ある場所において探す

https://api.example.com/search/

3. 大文字小文字が混在していないURL

3-1. 小文字を使う

❌ 大文字小文字が混在している

https://api.example.com/User/123

⭕ 小文字のみにする

https://api.example.com/users/123

4. 改造しやすい(Hackable)URL

:::message 改造しやすい(Hackable)とは、 APIのドキュメントを熟読しなくても、構造が想像しやすいという意味 :::

4-1. 小文字を使う

⭕ v1がversionを表し、version 1.0が予想できる ⭕ itmes/123は、itmesの中のidが123を取得している事が予想できる ⭕ 別のitmesならitmes/234などにしたら取得出来そう

https://api.example.com/v1/itmes/123

5. サーバー側のアーキテクチャが反映されていないURL

5-1. 言語を隠す

❌ 言語がPHPである事が分かる :::message PHPの脆弱性を突いてくる悪い人がいる :::

https://api.example.com/cgi-bin/get-user.php?user=100

⭕ 言語などの情報を開示しない

https://api.example.com/users/123

6. ルールが統一されたURL

6-1. ルールを定める

❌ idの指定がURL毎でバラバラ ❌ friends,friendで複数形と単数形が混在

https://api.example.com/friends?id=100
https://api.example.com/friend/100/message

⭕ friendsの複数形で統一 ⭕ idを使わないで統一

https://api.example.com/friends/100
https://api.example.com/friends/100/messages

HTTPメソッド

メソッド名 説明
GET リソースの取得
POST リソースの新規登録
PUT 既存リソースの更新
DELETE リソースの削除
PATCH リソースの一部変更
HEAD リソースのメタ情報の取得

PUTメソッドとPATCHメソッドの違い

  • PUTメソッド: もともとあるリソースを置き換える
  • PATCHメソッド: もともとあるリソースの一部を置き換える

:::message 1MBのような大きなデータの一部のデータを更新したい場合は、PATCHメソッドを使う :::

目的 メソッド エンドポイント
ユーザー一覧の取得 GET https://api.example.com/v1/users/
ユーザーの新規登録 POST https://api.example.com/v1/users/
特定ユーザー情報の取得 GET https://api.example.com/v1/users/:id
ユーザーの情報の更新 PUT/PATCH https://api.example.com/v1/users/:id
ユーザーの情報の削除 DELETE https://api.example.com/v1/users/:id
ユーザーの友達一覧の取得 GET https://api.example.com/v1/users/:id/friends
友達の追加 POST https://api.example.com/v1/users/:id/friends
友達の削除 DELETE https://api.example.com/v1/users/:id/friends/:id
近況の投稿 POST https://api.example.com/v1/updates
近況の編集 PUT https://api.example.com/v1/updates/:id
近況の削除 DELETE https://api.example.com/v1/updates/:id
特定ユーザー近況の取得 GET https://api.example.com/v1/users/:id/updates
友達の近況一覧の取得 GET https://api.example.com/v1/users/:id/friends/updates

ページネーションについて

:::message 相対位置ではなく、絶対位置を使ってlimit,offsetをページネーションを行う :::

❌ 相対位置だと、データ数が増えるとパフォーマンスが下がる ❌ 相対位置だと、データの更新によってデータの順番がズレると取得するデータもズレる

⭕ 絶対位置でidで検索だと、データ数が増えてもパフォーマンスは下がらない ⭕ 絶対位置でidで検索だと、データ数が増えても取得するデータはズレない

Expiration Model (期限切れモデル)

レスポンスデータに期間を決める。期限が消えたら、再度アクセスをする

Validation Model (検証モデル)

現在保持しているキャッシュが最新であるかを確認する。データが更新された場合にのみ取得する

おわりに

Oreillyを初めて読みました。 自分には難しいと思っていましたが、そこまで難しいと感じなかったです。 Oreillyは学びが多く気に入りました!