api設計

APIの設計ってどうやるの？

鈴木雄登

APIの種類

• よく使われるAPIの利用目的

–公開しているWebサービスへのアクセス用API

–他のページに貼り付けるウィジェット

– AJAXを駆使したページ用のAPI

–スマホアプリ用のAPI

– ソシャゲ用のAPI

–社内システムとの連携API

こんなサービスも

Programmable Web

でもAPIの設計ってあんまり解説してない

アジェンダ

• APIの設計を始める前に

• エンドポイントの設計

• レスポンスデータの設計

APIの設計を始める前に

設計に入る前に決めるべきこと

• 何をAPIで公開するのか？

–全データのAPIを作るのか？

–全てのAPIを作るのは、時間がかかるが、ユーザも増え思いがけないメリットも見つかる

• 誰を対象にしたAPIか？

–ユーザを想定しなければ、使いやすいAPIというものは作れない

アプリケーションを作るのと同じで、

誰に向けた設計かを意識するだけで、

使いやすさは全然変わってくる

エンドポイントの設計

エンドポイントって？

http://api.example.com/users

APIにアクセスするためのURI

エンドポイント＝ユーザが一番見る情報

→ 覚えやすくどんな機能を持つURIなのかひと目でわかるものに

エンドポイント設計時の6箇条

1. 短く入力しやすいURI

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

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

4. HackableなURI

5. サーバ側のアーキテクチャによらないURI

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

HackableなURIを目指す

• Hackable ＝ハックしやすい

–修正することで別のURIにするのが容易なもの

http://api.example.com/v1/items/1234 アイテムアイテムID

サーバの構造は関係ない！

http://api.example.com/v1/items.php

http://api.example.com/v1/cgi-bin/items.php

ルールは統一しよう

http://api.example.com/v1/items

http://api.example.com/v1/item?id=12

http://api.example.com/v1/items/12?status=1

複数形が混ざっていたり、URLのパスが統一されてないものは、ユーザが混乱してしまう

細かい注意点

• 単語の注意点

–複数形の名詞にする

–利用する英語に気をつける

–エンコード文字列は使わない

–単語のつなぎはハイフン

メソッド

• GET – 基本的にサーバのリソースを変更させない

• POST – 新しいリソースの送信（新規登録）

• PUT – URIで指定し、リソースを全更新

• DELETE – 削除

• PATCH – 指定した一部のリソースのみ更新

レスポンスデータの設計

レスポンス設計時の注意点

• ChattyなAPIを作らない

• データはフラットのほうがいいのか

• 配列で返すかオブジェクトで返すか

• レスポンスのケース

• エラーレスポンス

ChattyなAPI：何度もアクセスしないと必要なデータが揃わないAPI

API ユーザ

面倒くさいAPIになる

ChattyなAPIは作らない

データはフラットなほうがいい？

{ "id":1, "name":"Yuto", "birthday":3, "gender":"male" }

{ "id":1, "name":"Yuto", "profile":{ "birthday":3, "gender":"male" } }

フラットにして無駄に階層が増えてしまっている。

答え：なるべくフラットがいい

{ "id":123, "date":"2014-12-02", "sender":{ "id":3, "gender":"male" }, "receiver":{ "id":10, "gender":"female" } }

階層が見やすい場合、OK

配列？フォーマット？

[{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}]

{“friends”: [{“id”:1,”name”:”taro”},{“id”:2,”name”:”hanako”}] }

OR

以下の３つの理由から２を推奨

• レスポンスデータが何を示しているかすぐわかる • データをオブジェクトに統一できる • セキュリティ上のリスクを避ける事ができる

JSONインジェクション

１、

２、

レスポンスの変数名

• わかりやすく、かつ短い名前に

例）userRegistrationDateTime→registeredAt

• ケースは利用しやすいほうで

Googleはキャメルと言っているが、

Twitterなどスネークの企業も多くある

キャメルかスネークか統一すること

• 慣習的でない省略は禁止

{“id”:1,”registeredAt”:”2015-5-5”}

エラーレスポンス

• ステータスコードは正しいものを返す

–登録失敗しているのに、200とかを返さない

• エラー内容をクライアントに返す

–ヘッダに入れるかボディにいれるかは好み

まとめ

• どんなユーザが使うかを決める

• その上でユーザが使いやすいものを想像し、APIを設計

• 設計におけるルール

–基本的には慣習に乗っ取る

–慣習が使いづらいものであれば、そこは直す

参考にした本

水野貴明著 2014年11月発行

by apigee free

api設計

Engineering