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

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

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

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

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

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

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

リソースとコレクションの理解

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

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

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

ベースURLは、製品を使用する開発者がWebアプリケーションで簡単に使用できるように、簡潔で、洗練されており、シンプルである必要があります。長く読みにくいベースURLは、見た目が悪いだけでなく、再コーディングしようとすると間違いを犯しやすいです。名詞は常に信頼されるべきです。リソース名詞を単数形または複数形に保つことについてルールはありませんが、コレクションは複数形に保つことが推奨されます。一貫性のために、すべてのリソースとコレクションでそれぞれ同じ複数形を持つことは良い習慣です。これらの名詞を自己説明的に保つことで、開発者はURLから記述されているリソースの種類を理解するのに役立ち、最終的にAPIを使用する際に自給自足できるようになります。写真共有アプリに戻りましょう。公開APIに/usersと/photosをコレクションとして持っているとします。これらがすべて複数形の名詞であることに注目してください。これらは自己説明的でもあり、/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設計ツールを使用して、Swagger（OpenAPI）仕様でAPIを次のように定義できます。

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を直感的に使用できるようにするパラメーターを設計できる方法のほんの一部です。最後に、疑わしい場合は、省略してください。特定のリソースまたはコレクションの機能について疑問がある場合は、次のイテレーションに残しておきましょう。APIの開発と保守は継続的なプロセスであり、適切なユーザーからのフィードバックを待つことは、ユーザーがクリエイティブな方法で統合およびアプリケーションを開発できる堅牢なAPIを構築する上で大いに役立ちます。

API設計を始める

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

REST APIのAPI設計を始めることに興味がありますか？Swagger API設計ツールがどのように役立つかをご覧ください。