REST APIは、「REprsentational State Transfer」というアーキテクチャパターンに従って、複数のアプリケーションやシステムが通信し、情報を交換するための強力なツールです。REST APIは非常に便利ですが、その作成と生産への配備は、非常に複雑で時間のかかるプロセスです。独自のREST APIを構築する場合、REST APIの命名に関するベストプラクティスも含めた、そのための業界のベストプラクティスの一部を熟知しておかないといけません。REST APIの命名の規則を使うことで学習曲線が劇的に低下し、新規デベロッパーやサードパーティユーザーにはAPIを使い始めやすくなるのです。

以下では、REST APIのエンドポイント（末尾）の命名の際に守るべき7つのヒントを紹介します。

目次

  1. URIの命名には名詞を使う
  2. 直感的でわかりやすく、省略のない名称を使う
  3. URIの階層を表すにはスラッシュを使う
  4. ハイフンで単語を区切る
  5. 小文字を使う
  6. 特殊記号を避ける
  7. ファイル拡張子を避ける
  8. まとめ

1. URIの命名には名詞を使う

REST APIには、【 https://api.example.com 】のように、アクセス可能なURLがあります。このURLのサブディレクトリは、別々のAPIリソースを表し、それはURIを使ってアクセスされるものです。例えば【 https://api.example.com/users 】というURIだと、特定のサービスのユーザーを含んだリストが返ってきます。

一般にURIは、実行される機能を表す動詞を付加するのではなく、リソースの内容を特定する名詞での命名が望ましいです。例えば、【 https://api.example.com/getUsers 】ではなく、【 https://api.example.com/users 】をとなるべきです。これは、CRUD（作成,、読み出し、 更新,、削除）機能が、例えば【 HTTP GET https://api.example.com/users 】のように、すでにHTTPリクエストで指定されているはずだからです。

URIの命名に名詞を使うのは、REST API命名のベストプラクティスですが、どのような場合に単数または複数名詞の使用が必要なのでしょうか。一般に、リソースが明らかに単数形の概念である場合を除き、例えば管理ユーザーを表す【 https://api.example.com/users/admin 】のように、複数形の名詞を使う方が望ましいです。

2. 直感的でわかりやすく、省略のない名称を使う

REST APIのエンドポイントに名前を付けるときは、直感的でわかりやすいURI名を使うべきですあり、第三者があなたのAPIを使ったことがなくても推測できるような名前が理想的です。具体的には、例えば【 https://api.example.com/users/123/first-name 】 の意味で 【 https://api.example.com/users/123/fn 】のような省略形や短縮形は避けましょう。ただし、例えば 【 https://api.example.com/users/identification-numbers 】 の意味で【 https://api.example.com/users/ids 】のような、その省略形が好まれたり最も一般的な用語である場合は、この限りではありません。

3. URIの階層を表すにはスラッシュを使う

REST APIは通常、階層構造になっています。たとえば、【 https://api.example.com/users/123/first-name 】 は、ID123番のユーザーのファーストネームを取得します。この階層を移動するには、「/」（スラッシュ）を使い、URIの左から右へ移動する際に一般的なものから特定のものへと移動します。

スラッシュはAPIの階層を示すのには適していますが、URLをスラッシュで締めると、スッキリするどころかややこしくなるので、例えば、【 https://api.example.com/users/ 】ではなく【 https://api.example.com/users 】にようにして、スラッシュは最後に付けないようにしましょう。

4. ハイフンで単語を区切る

【 https://api.example.com/users/123/first-name 】など、REST APIエンドポイントに複数の単語が含まれている場合、ハイフンで単語を区切る必要があります。 これは通常、アンダースコア（first_nameなど）やキャメルケース（firstNameなど：（これは大文字を使用するため推奨されません（以下参照））を使用するよりも明確でユーザーフレンドリーです。

5. 小文字を使う

APIのURLには、できるだけ小文字を使いましょう。これは主に、URI標準のRFC 3986仕様が、URLのスキームとホストコンポーネントを除き、ケースセンシティブであることを示しているためです。URIの小文字化は広く普及されており、大文字小文字の不統一による混乱を避けるのにも有効です。

6. 特殊記号を避ける

特殊記号は不要なだけでなく、ユーザーの混乱をまねき、技術的に複雑なものになりかねません。URLはアスキー文字セットでのみ送受信できるため、API URLはすべてアスキー文字のみを含むものであるべきです。

さらに、「安全でない」アスキー文字の使用も避けるようにしましょう。これは、例えばスペース文字に対する「%20」のように、混乱やセキュリティ上の問題を防ぐために大抵はエンコードされており、URLの「安全でない」アスキー文字には、スペース（"   "）のほか、大括弧（[ ]）、山括弧（<>）、中括弧（{}）、パイプ（|）などがあります。

7. ファイル拡張子を避ける

APIコールの結果は特定のファイルタイプかもしれませんが、ファイル拡張子は長さと複雑さを加えてしまうことから、URIではおおむね不要と見なされており、例えば、【 https://api.example.com/users.xml 】ではなく、【 https://api.example.com/users 】 を使う必要があります。実際、ファイル拡張子を使うと、後で結果のファイルタイプを変更したときにエンドユーザーに問題が発生する可能性があります。

結果のファイルタイプを指定したい場合は、代わりにコンテントタイプエンティティヘッダを使うことができます。

まとめ

REST APIのエンドポイントの命名規則がたくさんあるので、独自のREST APIの構築に長い時間がかかるのは当然ですが、Integrate.ioのようなAPI管理サービスはそうではありません。

Integrate.ioは、一行のコードも書かずにREST APIを自動生成し、管理することができる、先進のAPI管理プラットフォームです。鉄壁のセキュリティ、数十のビルトイン統合、24時間365日のサポートにより、企業のデジタル化がかつてないほど簡単に実現できます。

データ統合プラットフォームであるIntegrate.ioでは、企業はクラウド上でデータの統合、処理、分析のための準備を行うことができます。コードや専門用語を有しなくても使用できる環境であるため、ハードウェア、ソフトウェア、または関連インフラに投資することなく、どのような組織・個人でもビッグデータがもたらす機会をご享受頂けます。
14日間無料トライアル、無料デモやご相談は、こちらのリンクよりリクエストをお願い致します。後ほど、弊社担当者よりご連絡させて頂きます。