Open12

Web API The Good Parts

koyukoyu

AmazonやTwitterがAPIを公開したことで普及するきっかけの要因になった話は面白かった

koyukoyu

APIのエコシステムに参加することで、サービス自身がユーザーに受け入れられやすくなるというのは、理解してた方が良いな、まあ個人レベルなら関係ないか

koyukoyu

APIを公開するリスクはあるか？

ユーザをまだそれほど集められていないサービスであれば、サービスの情報で済むという人はあまりないでしょう。むしろ情報をよく活用してくれる人が登場して、サービスに付加価値をつけてくれる可能性の方が高いでしょう。

koyukoyu

ウェブAPI美しくするには

  • 仕様が決まっているものに関しては、仕様に従う
  • 腫瘍が存在してないものに関しては、デファクトスタンダードに従う
koyukoyu

確かに覚えやすくわかりやすいURIってよく言うけどちょっと漠然とした言葉だな。

もう少し具体的な指標

  • 短く入力しやすいURI
  • 人間が読んで理解できるUI
  • 改造しやすい（Hackableな）URI
  • サーバー側のアーキテクチャが反映されていないURI
  • ルールが統一されたURI
koyukoyu

人間が読んで理解できるURI

以下写真例のように意味のわからない単語は使わない
さらに、数字の羅列を使う場合は、一つ前の名称をusersにするなどして、数字の意味を明確化することが大事

koyukoyu

URIに限らず、前の職場でも省略は基本使わないようにしてたけど、国際企画として標準化されているものはそれを使ったほうがいいんだな
ISO 639の航空会社や空港表すコードとか
日本航空はJL、羽田空港は、HNDなど

koyukoyu

理解しやすい英単語の判断基準

理解したURLに英単語を使うと言うのは一般的だけどもその英単語の中でもよく使われている単語を選ぶ必要がある。しかし英語ネイティブではない人には難しいので、実際のAPIを見てみるのが1番良さそう
ProgrammableWebで確認

追加
閉鎖されてるから以下が良いかも
https://apilayer.com/marketplace?utm_source=any-api&utm_medium=any-api-redirection&utm_campaign=any-api-redirection

koyukoyu

問題があります！！！

getUserNameのような場合はこのようないわゆるキャメルケースにしたほうがわかりやすいのではないか、と思うかもしれません。しかしこれは、get_user_name や get-user-name
のようにすればよいのではないかというとそうではなく、getUsernameというような名前の付け方にそもそも問題があります。これについては後ほど述べます。

koyukoyu

改造しやすい（Hackableな）URI

あるURLから他のURLを想像することが可能であれば、ドキュメントを見なくて開発進めることができる。
サーバー側の都合はサーバー内で処理をして、利用者にそれを意識させないのは美しい設計だと言えるでしょう。

極端な例だが、なんらかの理由で以下のURI担っている時、ユーザーはいちいちID範囲を確認しなきゃいけなくなる。

IDの範囲 エンドポイント
1 ～ 300000 http://api.example.com/v1/items/alpha/:id
400001 ～ 500000 http://api.example.com/v1/items/beta/:id
500001 ～ 700000 http://api.example.com/v1/items/gamma/:id
700001 ～ http://api.example.com/v1/items/delta/:id
koyukoyu

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

言語によってURIなど変わることがないようにってことか

koyukoyu

ルールが統一されたURI

以下のようなエンドポイントがある

友達の情報の取得
http://api. example.com/friends?id=100
※メッセージの投稿
http://api. example.com/friend/100/message

friendsの複数形が違ったり、クエリとURIで検索したりと統一感がない。