

現在私の会社では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で構築できるのか教えていただきたいです。


CC BY-SA 4.0
2018-07-15T16:05:35.473
46641
2018-08-12T05:02:52.150
2018-08-12T05:02:52.150
754
29325
question
ruby-on-rails api rest
APIの数が膨大になった時のAPI名の付け方について質問


名前の付け方って難しいですよね。  
APIと直接ではなくて申し訳ありませんが、ご指定のような<頭文字>+連番5桁のような名前つけは  
古いシステムではよく採用されているようです。名前空間が狭くて、ユニークな名前を付けづらかった時の名残ではないかと思います。  
なので、「名前として存在するか」という意味では普通に存在します。  
そういったシステムをお使いの場合、頭文字＋連番で完全に機能を把握している人がいたりして、なかなかモダンな名前つけに変更できないといったことが起きたりもします。

以上、ご参考まで


CC BY-SA 4.0
2018-07-15T21:49:35.733
46644
2018-07-15T21:56:52.283
2018-07-15T21:56:52.283
10174
10174
46641
answer


まず大前提として名付けよりもドキュメントやソースコードがしっかりしているほうが遥かに重要だと思います。最低限ドキュメントがあれば機能や動作についての詳述を取得することができるので。  
設計・開発を行うということは全体像が見えているわけでもない環境下で機能を作り上げていくということなので、そうした状況下で(α,β版)で適切な名づけに拘泥することは無駄だと思います。  
もしデータベースの管理を行ったことがあるならばよく考えて下さい。APIにおける名前とはデータベースでいうところのIDに相当します、IDは自動連番かハッシュ値を用いますよね？IDにある人為的な値を指定するということに躊躇するでしょう。(それはIDの管理を機械が行うのではなく手動で行うことを意味するから)  
もしもラムダ関数というものをご存知でしたらよく考えてください。ラムダ関数は何故便利なのでしょうか？名前を付ける必要がなく、人間が管理する必要がないからです。  
APIの名づけといっても使用できる文字は多くても十数文字ぐらいでしょう。それで機能を詳述しきることは不可能です。  
名づけに求められることとしては誰がAPIを使用して、その使用者がどのような暗黙的な(前提)知識を保有していて、だからどのような情報を記述せずに済むかという観点が第一。  
第二にAPIの全体像の中において各APIがどのような立ち位置(階層構造)にあって、どのように部分を為すのか、あるいはAPI同士がどのような差異を持っているのかを明確にし、検索を容易にすること。  
第三はAPIの名前が極力不変となるように言葉を援用すること。  
APIにおける名づけというのは機械的管理を放棄してでも人間的なインターフェースを構築するということだと思いますので、最低限この3要件を満たさないならば名づけの意味がないと思います。


CC BY-SA 4.0
2018-07-16T06:42:12.550
46652
2018-07-16T06:42:12.550
25980
46641
answer


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

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`を使うケースは多いです。

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


CC BY-SA 4.0
2018-07-17T03:33:51.293
46667
2018-07-17T05:11:53.470
2020-06-17T08:14:45.997
-1
15171
46641
answer


メンテナンス性を上げるために略語や造語、記号などは使うべきではないと考えています。  
camelCase, snake_case, kebab-caseなど単語で区切って命名したいですが、  
今のルールを完全に崩壊させると困るということでしたら接頭辞はどうでしょうか？  
接頭辞＋命名で何とか管理できませんか？

API名を見て機能の概要が分からないのはどうなんでしょうか？


CC BY-SA 4.0
2018-07-18T04:17:41.673
46686
2018-07-18T04:17:41.673
46641
answer


すべてにユニークな名前を付けるのは難しくても、大まかな機能のくくりなどで分類してみて  
`接頭辞`+`連番`、などにしてみるとか。  
過去の名前は残しつつ、可能であれば別名でアクセスする手段も用意して少しずつ整理する…という手もありじゃないでしょうか。


CC BY-SA 4.0
2018-07-18T12:24:51.680
46702
2018-07-18T12:24:51.680
3060
46641
answer