WebAPIの命名規則 スネークケースvsキャメルケース🐍💥🐫

この記事について

WebAPIのリクエスト&レスポンスボディの命名規則にスネークケースとキャメルケースのどちらを採用すべきか考えてみた系の記事

背景

現在自分のいるプロジェクトでは、バックエンドをPython、クライアントをTypeScript(Web)とKotlin(Android)で開発している
先日一通り技術検証が完了したので振り返りを行ったところ、クライアント側のチームから「APIレスポンスをスネークケースからキャメルケースに変換するのが面倒だしバグの温床になる」という声が上がった
それに対するメンバーの反応は「WebAPIはスネークケースが事実上の標準仕様だから従え」とか「どうせキャメルケース使う言語でしか触らないから合わせちゃってもいいんじゃね」といった感じ

そこで今一度🐍と🐫のメリットデメリットをまとめてどちらを採用すべきか検討してみようと思いこの記事を書いた

主要なAPIは🐍と🐫どっち使ってる？

まずはWebAPI=スネークケースという認識が正しいのか確かめるために主要なAPIを確認してみよう

主要なAPIの命名規則まとめ

有名どころのAPIリファレンスを眺めて表にまとめてみた

API	🐍or🐫
Twitter	🐍
Facebook	🐍
Stripe	🐍
PayPal	🐍
Amazon AWS	🐫(Upper)
Microsoft Azure	🐫(Lower)
Google	🐫(Lower)

スネークケースの方が多いけど普通にキャメルケース使っているAPIも多かった
なので、少なくともWebAPI=スネークケースという認識が主流ではあっても絶対的ではなさそう🤔

🐍と🐫のメリットデメリット

とりあえずキャメルケースも普通に選択肢には上がることは確認できたので、それぞれのメリットデメリットを整理してみる

🐍の場合

メリット

• WebAPIの命名規則として一般的
• PythonやRubyなどもスネークケースなのでそれらと一貫性を保てる
• RDBのカラム名もスネークケース
• NoSQLの場合はオブジェクトを入れる≒アプリケーションコードと同じ命名規則なのでスネークケースでも違和感ない

デメリット

• Webのクライアントでよく採用されるJS/TSとは相性が悪い(これらはキャメルケース)
• Windows、モバイルの場合も(C#、Java/Kotlin、Swiftなど)相性が悪い

🐫の場合

メリット

• Webのクライアントで使われる言語と相性がいい

デメリット

• WebAPIの命名規則として一般的とはいえない
• RDBとは相性が悪い

命名規則の採用基準を考えてみる

メリットデメリットはわかったのでそれを踏まえてどちらを採用すべきかの基準を決めよう

DBと利用者のコードの命名規則が重要

似たようなことを考えてる人がいないか調べたところ、以下のような記述を発見

"このAPIは誰が使うか？" は設計する上で重要なので、最初に定義しておいたほうが良いでしょう。
例えば、社内の開発者が使うか、一般ユーザが使うかで考慮する範囲が変わってきます。

社内の開発であれば、開発のしやすさなどが優先度として高くなりますが、
一般ユーザー（外部）の場合、加えてWebAPIを広く使ってもらうための視点も必要になります。

The DB schema also has a lot to do with the case of the response data. Most backend devs don’t expressly want to think too much about case of the response, so whatever the database sends, is what the consistency across the project is then based on.

I have never really given this much thought but now that you have mentioned it, I think it's better to be consistent with whichever case one eventually chooses.

要点をまとめると、

• 一貫性を保つことが超重要
  • ここでは何を指すかというと、DBのカラム名等の命名規則 API利用者(クライアント)のコードの命名規則 APIのリクエスト＆レスポンスの命名規則の3つを統一すること
• APIの利用者がだれかという観点も同じくらい大事
  • 利用する人が限られている場合はその人達の要望に合わせてあげた方がいい
  • 逆に広く一般的に公開するAPIの場合はWebAPIとして一般的なスネークケースの方がいい

結論

一貫性を保つをキーワードに🐍と🐫どっちを採用すべきか判断しましょう

命名規則の一貫性を保つ

DBのカラム名、API利用者のコード、APIのリクエスト＆レスポンスのすべてで同じ命名規則を使うことが望ましい
これら3つの命名規則についてまとめたので総合的に判断して決めよう

DB

大きく分けてRDBとNoSQLに分けられる
どちらを採用するかはバックエンドの種類によるしここでは到底書ききれないのでそれぞれの命名規則についてだけ

RDB

スネークケースを採用する方が一般的

NoSQL

Key-Value形式で保存される関係上、アプリケーションコードの命名規則そのままに保存した方がいい
つまりスネークケースでもキャメルケースでもどっちでもいい

API利用者のコード

このAPIを利用する人にとって都合がいい方を採用しよう

APIの公開範囲

AWSやAzureのような一般的に公開されているAPIを作る場合は、より一般的に採用されている方＝スネークケースにする
逆に、アプリケーションの内部でしか使用しない場合にはアプリのクライアントで使用している言語にとって都合がいい方にする

APIの利用者が限定的か否か

TwitterやYoutubeのようにいろんな人が使うアプリのAPIの場合は先述の通りスネークケースの方がいい
しかし、限られた界隈の人しか使わないニッチなアプリやサービスの場合はその人たちにとって都合がいい方にする

例

• 機械学習に関するサービスのAPI
  • 機械学習＝Python＝スネークケースなのでスネークケースを採用
• モバイルアプリに関するサービスのAPI
  • モバイル＝Java Kotlin Swift＝キャメルケースなのでキャメルケースを採用

参考記事

https://qiita.com/mkin/items/13b0e78b69969097c267#%E3%81%BE%E3%81%A8%E3%82%81
https://dev.to/imichaelowolabi/what-case-should-your-api-request-response-be-ggo