API設計におけるベストプラクティス

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

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

一般的に、効果的なAPI設計は次の特性を備えています。

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

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

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

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

リソースは、RESTの概念にとって不可欠です。リソースとは、それ自体で参照するのに十分重要なオブジェクトです。リソースには、データ、他のリソースとの関係、および関連する情報へのアクセスと操作を可能にするためにリソースに対して実行されるメソッドがあります。 リソースのグループはコレクションと呼ばれます。コレクションとリソースの内容は、組織とコンシューマーの要件によって異なります。たとえば、製品のユーザーベースに関する基本情報を取得することが市場にとって有益であると思われる場合は、これをコレクションまたはリソースとして公開できます。 Uniform Resource Locator（URL）は、リソースのオンラインロケーションを識別します。このURLは、APIのリソースが存在する場所を指します。ベースURLは、このロケーションの一貫した部分です。 写真共有アプリの場合、アプリを使用するユーザーに関するデータをコレクションとリソースを通じて公開し、適切なURLでアクセスできます。

1. /users：ユーザーのコレクション
2. /users/username1：特定のユーザーに関する情報を持つリソース

URLは名詞で記述する方が良い

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

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

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

(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つの可能性のある結果があります：-

1. クライアントアプリケーションが誤った動作をした（クライアントエラー - 4xx応答コード）
2. APIが誤った動作をした（サーバーエラー - 5xx応答コード）
3. クライアントとAPIが機能した（成功 - 2xx応答コード）

API を利用するエンドユーザーが問題に直面した際に、彼らが成功できるようにサポートすることは、開発者体験を向上させ、API の誤用を防ぐ上で非常に重要です。エラーレスポンスは、明確かつ簡潔に記述してください。エンドユーザーが原因の修正に着手できるだけの十分な情報をエラーコードに含め、必要に応じて追加ドキュメントへのリンクを提供してください。

すべての GET レスポンスの例を示してください。

適切に設計された API は、URL に対する正常な呼び出しで期待されるレスポンスの例も備えています。このレスポンス例は、シンプルでわかりやすく、すぐに理解できるものであるべきです。目安として、開発者が成功したレスポンスがどのようなものかを 5 秒以内に理解できるようにすると良いでしょう。 フォトシェアリングアプリを例にとると、/users と /photos という URL を定義しました。/users コレクションは、アプリに登録したすべてのユーザーのユーザー名と登録日を配列で返します。 API 設計ツールを使用して、Swagger (OpenAPI) 仕様で API を次のように定義できます。

1. responses:
2. 200:
3. description: ユーザーに関する情報が正常に返されました。
4. schema:
5. type: array
6. items:
7. type: object
8. properties:
9. username:
10. type: "string"
11. example: "kesh92"
12. created_time:
13. type: "dateTime"
14. example: "2010-01-12T05:23:19+0000"

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

1. {
2. “data”:[
3. {
4. “Username”:“example_user1”,
5. “created_time":“2013-12-23T05:51:14+0000 ”
6. },
7. {
8. “username”:“example_user2”,
9. “created_time":“2015-3-19T17:51:15+0000 ”
10. }
11. ….
12. ]
13. }

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

リクエスト

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

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

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

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

1. GET /users/kesh92

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

API 設計を始める

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

REST API の API 設計を始めたいですか？ Swagger API 設計ツールがどのように役立つかをご覧ください。