API設計のベストプラクティス

2016年10月10日

優れたAPI設計は、API戦略を完璧にしようとするチームにとってよく話題になるテーマです。以前のブログ記事では、API設計の重要性について簡単に説明しました。適切に設計されたAPIの利点には、開発者エクスペリエンスの向上、ドキュメント作成の高速化、APIの採用率の向上が含まれます。しかし、優れたAPI設計には具体的に何が含まれるのでしょうか？このブログ記事では、RESTful APIを設計するためのいくつかのベストプラクティスを詳しく説明します。

適切に設計されたAPIの特性

一般的に、効果的なAPI設計には以下の特性があります。

- 読みやすく、扱いやすい：適切に設計されたAPIは扱いやすく、そのリソースと関連する操作は、常に使用する開発者によってすぐに記憶されます。
- 誤用しにくい：優れた設計のAPIを実装して統合するプロセスは簡単であり、誤ったコードを記述する可能性は低くなります。情報を提供するフィードバックがあり、APIのエンドコンシューマに厳格なガイドラインを強制しません。
- 完全かつ簡潔：最後に、完全なAPIは、開発者が公開するデータに対して本格的なアプリケーションを作成できるようにします。完全性は通常時間とともに達成され、ほとんどのAPI設計者と開発者は既存のAPIの上に incrementally 構築します。これは、APIを持つすべてのエンジニアまたは企業が目指すべき理想です。

以下の概念を説明するために、写真共有アプリの例を挙げます。このアプリでは、ユーザーが写真をアップロードし、撮影場所と、写真に関連する感情を表すハッシュタグを付けて特徴付けることができます。

コレクション、リソース、およびそのURL

リソースとコレクションを理解する

リソースはRESTの概念の基本です。リソースは、それ自体で参照されるほど重要なオブジェクトです。リソースはデータ、他のリソースへの関係、および関連情報へのアクセスと操作を可能にするメソッドを持っています。リソースのグループはコレクションと呼ばれます。コレクションとリソースの内容は、組織および消費者の要件によって異なります。たとえば、製品のユーザーベースに関する基本情報を取得することが市場に利益をもたらすと考える場合、これをコレクションまたはリソースとして公開できます。ユニフォームリソースロケータ（URL）は、リソースのオンライン上の場所を識別します。このURLは、APIのリソースが存在する場所を指します。ベースURLは、この場所の一貫した部分です。写真共有アプリの場合、適切なURLを介してアクセスされるコレクションとリソースを通じて、アプリを使用するユーザーに関するデータを公開できます。

/users: ユーザーのコレクション
/users/username1: 特定のユーザーに関する情報を含むリソース

名詞はURLをより適切に記述する

ベースURLは、製品を使用する開発者がWebアプリケーションで簡単に使用できるように、すっきりとエレガントでシンプルである必要があります。長くて読みにくいベースURLは、見栄えが悪いだけでなく、再コーディングしようとするときに間違いを起こしやすいです。名詞は常に信頼されるべきです。リソース名詞を単数形にするか複数形にするかというルールはありませんが、コレクションは複数形に保つことをお勧めします。一貫性のために、すべてのリソースとコレクションでそれぞれ同じ複数形を持つことは良い習慣です。これらの名詞を自己説明的に保つことで、開発者はURLから記述されたリソースの種類を理解し、最終的にAPIを操作する際に自立できるようになります。写真共有アプリに戻ると、/usersと/photosをコレクションとして持つ公開APIがあるとします。これらがすべて複数形の名詞であることに注目してください。これらは自己説明的でもあり、/usersと/photosがそれぞれ製品の登録ユーザーベースと共有写真に関する情報を提供すると推測できます。

HTTPメソッドでリソース機能を記述する

すべてのリソースには、APIによって公開されるデータを操作するために、それらに対して実行できる一連のメソッドがあります。RESTful APIは、主にHTTPメソッドで構成されており、これらのメソッドは任意のリソースに対して明確に定義された一意のアクションを持ちます。RESTful APIの任意のリソースまたはコレクションのCRUD操作を定義する、一般的に使用されるHTTPメソッドのリストを以下に示します。

メソッド	説明
GET	リソースの表現を取得するために使用されます。
POST	新しいリソースとサブ・リソースを作成するために使用されます
PUT	既存のリソースを更新するために使用されます
PATCH	既存のリソースを更新するために使用されます
DELETE	既存のリソースを削除するために使用されます

(PUTとPATCHの違いを知りたい場合は、StackOverflowのこのフィードをチェックしてください。) URLから動詞を削除することも良いアイデアです。GET、PUT、POST、DELETEの操作は、URLで記述されたリソースを操作するためにすでに使用されているため、URLに名詞の代わりに動詞があると、リソースの操作が混乱する可能性があります。写真共有アプリでは、/usersと/photosをエンドポイントとして、APIのエンドコンシューマは上記のRESTful CRUD操作を使用して、直感的にそれらを簡単に操作できます。

応答

開発者の成功を助けるためにフィードバックを与える

開発者に製品の使用状況に関する適切なフィードバックを提供することは、採用率と定着率の向上に大きく貢献します。すべてのクライアントリクエストとサーバー側レスポンスはメッセージであり、理想的なRESTfulエコシステムでは、これらのメッセージは自己記述的である必要があります。良いフィードバックには、正しい実装に対する肯定的な検証と、ユーザーが製品の使用方法をデバッグおよび修正するのに役立つ誤った実装に関する情報提供のエラーが含まれます。APIの場合、エラーはAPIの使用に関するコンテキストを提供するための優れた方法です。エラーを標準のHTTPコードに合わせてください。誤ったクライアント側の呼び出しには、400番台のエラーが関連付けられている必要があります。サーバー側のエラーがある場合は、適切な500番台のレスポンスが関連付けられている必要があります。リソースに対して使用された成功したメソッドは、200番台のレスポンスを返す必要があります。多くのレスポンスコードがあります。詳細については、このREST APIチュートリアルをチェックしてください。一般的に、APIを使用する際には3つの可能な結果があります。-

クライアントアプリケーションが誤動作した（クライアントエラー - 4xxレスポンスコード）
APIが誤動作した（サーバーエラー - 5xxレスポンスコード）
クライアントとAPIが機能した（成功 - 2xxレスポンスコード）

APIの利用中にエンドユーザーが問題に遭遇した際に、成功への手助けをすることは、開発者エクスペリエンスを向上させ、APIの誤用を防ぐ上で非常に重要です。これらのエラー応答を適切に記述し、しかし簡潔で分かりやすく保ってください。エラーコードにエンドユーザーが原因の修正に取り掛かるのに十分な情報を提供し、さらに情報が必要だと感じる場合は、追加ドキュメントへのリンクを提供してください。

すべてのGETレスポンスに例を挙げる

適切に設計されたAPIには、URLへの成功した呼び出しで期待できる応答の種類の例も含まれています。この例の応答は、シンプルで分かりやすく、迅速に理解できるものである必要があります。良い経験則として、開発者が成功した応答が5秒以内に何を提供するかを正確に理解できるように助けることです。写真共有アプリに戻ると、/usersと/photosというURLを定義しました。/usersコレクションは、アプリに登録しているすべてのユーザーのユーザー名と参加日を配列で提供します。次のAPIデザインツールを使用して、APIをSwagger（OpenAPI）仕様で定義できます。

responses:
        200:
          description: Successfully returned information about users 
          schema:
            type: array
            items:
              type: object
              properties:
                username:
                  type: "string"
                  example: "kesh92"
                created_time:
                  type: "dateTime"
                  example: "2010-01-12T05:23:19+0000"

エンドユーザーが成功したGET呼び出しから期待できる各レスポンス項目に記述されたデータ型と例に注目してください。エンドユーザーがJSONで受け取る成功したレスポンスは次のようになります。

{
   “data”:[
      {
         “Username”:“example_user1”,
         “created_time":“2013-12-23T05:51:14+0000         ”
      },
      {
         “username”:“example_user2”,
         “created_time":“2015-3-19T17:51:15+0000         ”
      }
….
   ]
}

エンドユーザーがGETメソッドでエンドポイントを正常に呼び出した場合、上記データと200番のレスポンスコードを取得して、正しい使用法を検証する必要があります。同様に、不正な呼び出しは、コレクションに対してユーザーがより適切に操作できるように、関連情報と共に適切な400番または500番のレスポンスコードを生成する必要があります。

リクエスト

複雑さをエレガントに処理する

公開しようとしているデータは、APIを扱うエンドユーザーにとって有益な多くのプロパティによって特徴付けられる可能性があります。これらのプロパティは、基本リソースを記述し、適切なメソッドで操作できる特定の情報の資産を分離します。APIは完全を目指し、開発者がシームレスに統合できるように、必要なすべての情報、データ、リソースを提供する必要があります。しかし、完全性とは、APIの一般的なユースケースを考慮に入れることを意味します。このような関係やプロパティは多数存在する可能性があり、それぞれにリソースを定義することは良い習慣ではありません。リソースが公開するデータの量も考慮に入れる必要があります。多くを公開しようとすると、特に負荷やパフォーマンスに関して、サーバーに悪影響を与える可能性があります。上記のケースと関係は、APIの設計において重要な考慮事項であり、適切なパラメータを使用して処理できます。クエリパラメータの「？」の後ろにプロパティと制限された応答を隠したり、パスパラメータを使用してクライアントが操作しているデータの特定のコンポーネントを分離したりできます。写真共有アプリの例を挙げましょう。特定の場所で共有されたすべての写真と特定のハッシュタグに関する情報を取得することは、開発者にとって役立つかもしれません。また、サーバー負荷を防ぐために、API呼び出しごとの結果の数を10に制限したいとします。エンドユーザーがボストンのすべての写真をハッシュタグ #winter で見つけたい場合、呼び出しは次のようになります。

GET /photos?location=boston&hashtag=winter&limit=10

複雑さがクエリパラメータとの単純な関連付けにどのように軽減されたかに注目してください。クライアントのリクエストに応じて特定のユーザーに関する情報を提供したい場合、呼び出しは次のようになります。

GET /users/kesh92

ここで、kesh92はusersコレクション内の特定のユーザーのユーザー名であり、kesh92の場所と参加日を返します。これらは、APIの完成を目指し、エンドデベロッパーがAPIを直感的に使用できるようにパラメーターを設計できる方法のほんの一部です。最後に、迷ったときは、やめてください。特定のRソースやコレクションの機能について迷いがある場合は、次のイテレーションに回してください。APIの開発とメンテナンスは継続的なプロセスであり、適切なユーザーからのフィードバックを待つことは、ユーザーがクリエイティブな方法でアプリケーションを統合および開発できる堅牢なAPIを構築する上で非常に重要です。

API設計を始める

すべての組織に当てはまる唯一のAPI設計アプローチはありません。上記の提案は単なる提案であり、ユースケースと要件に応じて使用または破棄できるアドバイスと推奨事項です。API設計が非常に重要である主な理由の1つは、エンドユーザーがAPIを使用できるようにすることです。彼らのニーズが、素晴らしいAPIを設計および構築するための指針となるべきです。

お読みいただきありがとうございます！さらにAPIリソースをお探しですか？Swaggerニュースレターを購読してください。最高のAPI記事、トレーニング、チュートリアルなどを毎月メールでお届けします。購読する