APIの数が膨大になった時のAPI名の付け方について質問


現在私の会社ではAPIの名前はapi1,api2,api3というような名前でapiを書いています。  
apiを呼ぶ時、api/v1/api1みたいな感じです。  
これだと何の何をするapiかわからないのです。

なぜこういう名前にしたかというと理由は二つあります。  
・昔apiの数が膨大になった頃、一つ一つに適切な名前をつけることが困難になったから  
・更新するプログラムで子テーブルの要素まで更新する場合、適切な名前が思いつかなくなった。

上記二つの理由から私の会社ではapi{n}という名前でapiを作ることが文化になりました。

また、APIを作る上で制約等がないためメンバーは、本来getメソッドが正しいところでもpostを使用したりと作る人によってバラバラです。

だから私はどうにかメンテナビリティが高くできないかということやRESTfulなAPIを作るにはどうしたらよいかを考えていて、  
上司に相談すると、考えた結果api{n}という名前でapiを作ることを決断したとのことでした。

色々調べましたが、私たちと同じように作成している事例を聞いたことないし調べても出てきませんでした。

実際私たちのサービスよりも大きいサービスでAPIの数も私たちのサービスよりも多いサービスはいっぱいあると思います。  
「apiの数が膨大になり、一つ一つに適切な名前をつけることが困難」という問題も当然あるとと思います。

どう解決しているのかの質問と、どのようにAPIを設計すれば上記のような問題を回避できるのか、RESTfulなAPIで構築できるのか教えていただきたいです。




日本の会社では、命名規則によって名前をつけるの難しいですよね。事務処理や帳票に英語名がついているケースはあまりないので、プログラムをする時に英語名をつけるのに結構苦労します。

Wikipediaの[「命名規則
(プログラミング)」のページ](https://ja.wikipedia.org/wiki/%E5%91%BD%E5%90%8D%E8%A6%8F%E5%89%87_\(%E3%83%97%E3%83%AD%E3%82%B0%E3%83%A9%E3%83%9F%E3%83%B3%E3%82%B0\))には、命名規則のビジネス上の価値として次のように書かれています。

>
> エンドユーザーが識別子の良否を意識することはほとんどないが、システムを引継いでゆくアナリストや開発者にとっては、識別子が適切に選定されていることで、システムが何をしているかを理解したり、さらには新たなビジネス所要に応じてソースコードをどのように修正・拡張すればよいかを判断することが極めて容易となる。
>
> 例えば、
>
> `a = b * c`
>
> コードは文法的に間違っているわけではないが、その意図・意味は見当もつかない。
>
> これに対して、
>
> `weekly_pay = hours_worked * pay_rate`
>
> というコードでは、少なくともアプリケーションの基本的な前後関係を理解している人には意味・意図がよくわかる（weekly_pay =
> 週給、hours_worked = 勤務時間、pay_rate = 時給）。

この趣旨は、よく理解できるのですが、命名規則では漢字を使うことは良くないこととされているため、どうしても無理やり英語に翻訳して命名する必要があります。ローマ字で書くという方法もあるのですが漢字と違ってすぐに意味がわからないし長ったらしくなります。そのため、「識別子」を見ても普段使っている言葉でないため理解の助けになるというメリットも減少するし、英語がよくわからない人間が翻訳すると意味不明な英語にすることも多くなってしまいます。

今回は、`API`の命名規則の問題なのですが、CMSやブログでURLをどうするかという問題も同じです。海外ではタイトル名をURLの最後につけるケースが多いのですが、日本語のサイトでそれをやると日本語URLになってしまいます。日本語URLを使うのが嫌な場合には、英語のタイトルを考えるの手間だしユーザーが英語で検索してくれる訳ではないので効果もないので`id`を使うケースは多いです。

結局、英語圏で作られた命名規則をそのまま日本に持ってくるのが問題で、会社や担当者のインターナショナル度を考慮してどうするか判断するしかないように思います。純日本の会社では、レガシーな`<頭文字>+連番`という命名を残した方が結構わかりやすいというケースは多いと思います。

