6

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

6
  • 1
    RestfulなAPI設計ということであれば、docs.microsoft.com/ja-jp/azure/architecture/best-practices/… が参考になるかもしれません。
    – user28902
    Commented 2018年7月15日 16:17
  • 2
    こちらも、参考になるとおもいます。restfulapi.net/resource-naming
    – Daichi
    Commented 2018年7月15日 23:36
  • ありがとうございます。参考にしてみます。
    – Tomo1986
    Commented 2018年7月16日 3:42
  • 1
    もしかしてですが、似たようなAPIいっぱいありません?条件違いの似たような情報取ってくるのに、条件をパラメータで受けずに。。。この条件のAPIはこれ。この条件のAPIはこれ。みたいな設計になってたりしません?
    – 豚吐露
    Commented 2018年7月17日 4:24
  • マルチポスト qa.atmarkit.co.jp/q/10566
    – htb
    Commented 2018年7月20日 0:30

5 件の回答 5

3

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

Wikipediaの「命名規則 (プログラミング)」のページには、命名規則のビジネス上の価値として次のように書かれています。

エンドユーザーが識別子の良否を意識することはほとんどないが、システムを引継いでゆくアナリストや開発者にとっては、識別子が適切に選定されていることで、システムが何をしているかを理解したり、さらには新たなビジネス所要に応じてソースコードをどのように修正・拡張すればよいかを判断することが極めて容易となる。

例えば、

a = b * c

コードは文法的に間違っているわけではないが、その意図・意味は見当もつかない。

これに対して、

weekly_pay = hours_worked * pay_rate

というコードでは、少なくともアプリケーションの基本的な前後関係を理解している人には意味・意図がよくわかる(weekly_pay = 週給、hours_worked = 勤務時間、pay_rate = 時給)。

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

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

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

1
  • なるほど。 わかりやすい説明ありがとうございます。 確かに日本語をそのまま略そうとしてしまうので「これはもう管理できない」となったのかもしれません。 引き続きこのままidで進めてみようかと思います。 ご回答ありがとうございました。
    – Tomo1986
    Commented 2018年7月17日 15:25
1

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

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

1

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

0

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

以上、ご参考まで

1
  • ほんと難しいです。 おわ、そうなんですか!! 知りませんでした><; ありがとうございます。
    – Tomo1986
    Commented 2018年7月16日 3:39
-1

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

3
  • すごく簡単なドキュメントと、ソースコードは全然汚いです。 apiの名前で悩むよりまず、ドキュメントとソースコードをしっかり書くことですね。 おっしゃる通り十数文字で何をするAPIか理解してもらうのは厳しいと思いました。 なので、API名はそのままidで、ドキュメントをきっちり作成しようと思います。ご回答ありがとうございます。
    – Tomo1986
    Commented 2018年7月17日 15:36
  • ある程度コードの整理ができて、APIの全体像が見えてきたときにAPI名をつけることを再度考えてみて下さい。全体像が見えると適切な、あるべき名前と命名規則がなんとなく見えてくると思います。 Commented 2018年7月18日 10:55
  • 2
    nag-j.co.jp/naglib/fl/funclist.htm#C06 例えばこれはNAGという商用ライブラリですが、APIとしてはあまりにもふざけた名前をしています、それでもビジネスとしては成り立つのです、ドキュメントさえしっかりしていればね。 Commented 2018年7月18日 10:57

この質問に回答するには、ログインする必要があります。

求めていた回答ではありませんか? のタグが付いた他の質問を参照する。