API 設計時に迷った時におすすめな Google Cloud の API 設計ガイド
レビューをする際にも同様で、その際に自分は何を参考にしてるのか、どこを見てもらえば良い設計などを伝えられるのかなどを共有することがあるのでまとめておきたいと思いました。
Google Cloud の API 設計ガイド
よく参考にしているサイトとして Google Cloud の API 設計ガイドがあります。
2017 年に公開されたものですが、今年に入っても定期的に更新されています。
設計パターンから命名規則まで一通りの情報がまとまっており、まずはこれに目を通してもらうのが良いと思っています。
私の場合は特にこちらに関しては意識をしています。
数多くの API で長期にわたって一貫したデベロッパー エクスペリエンスを提供するために、API で使用されるすべての名前は、次の特徴を備えていることが推奨されます。
・シンプル
・直感的
・整合性
レビューをする際にも同様で、まずは直感的に理解できるか？その後に他の API や命名と整合性があるのか？もっとシンプルな表現はないのか？などを見ています。
個人的なアンチパターン
上記を実現する上で、避けた方が良いかなと思うことがあります。
とりあえず Google 翻訳で出てきたものをそのまま使う
前に他の人と話してて思ったのですが、とりあえず Google 翻訳にかけて一番上に出てくるものを採用する人がいる模様。
ちょっとしたニュアンスの違いで適切な単語は変わるので、ちゃんと比較をした方が良いです。
英単語の方もですが、翻訳に使用した日本語の方もいくつか捉え方というか候補があると思うので、日本語も適切なのか確認しつつしっくりくる単語を探す必要があります。
例えば、同じ食べ物という表現でも、食べ物、ご飯、ランチ、エサ、料理 とかとか。
自分がわからない単語を使用する
壊滅的に英単語わからない場合にはなんとも言えませんが、自分がわからないということは他のメンバーが見てもわからない可能性があります。
結局みんな調べないとわからないような単語を使用してしまうと、誰も直感的に理解できなくなります。
こちらに関しても、先ほどの API 設計ガイドの命名規則にも下記の記載があり、意識をした方が良いポイントだと思います。
多くの開発者は英語が母語ではないため、大部分の開発者が API を簡単に理解できるようにすることが、これらの命名規則の 1 つの目標です。
これが発生する場合には、日本語の表現を難しく考えすぎているかもしれません。
難しい日本語の表現から英語を考えるので、英単語がわからないなどは発生する可能性があります。
辞書の最後の方にのっているからという理由で良しとしてしまうと、
この単語ってこういう意味もあるんだという発見はここでは不要です。
ぱっと見た際に、みんなが同じような理解ができる単語を選ぶようにしましょう。
単語はたくさんあるので、もっと最適なものがあるはずです。
公開されている API を参考にする
1から全部考えるのは大変なので、ある程度他のサイトがどのように作成をしているのか確認するのもおすすめです。
私の場合は Github や Twitter などを参考にすることが多いです。
docs.github.com developer.twitter.com
そこそこちゃんとしたサイトのものであればなんでも良いのですが、普段自分が使用しているものだと理解しやすいと思います。
どういうデータが保存されていて、どんなページがあるのかがわかる方が想像しやすいからです。
