REST APIベストプラクティス

こんにちは、Habr！ Krishna Srinivasanによる記事「 REST API Best Practices 」の翻訳を紹介します 。



RESTは、サービスを外部に提示するための一般的なアプローチになりつつあります。 その人気の理由は、そのシンプルさ、使いやすさ、HTTP経由のアクセスなどです。 ネットワークを介してアクセス可能なすべてのデータはRESTと見なされるという誤解がありますが、そうではありません。 この記事では、独自のRESTアプリケーションを実装する際に常に覚えておくべきいくつかのベストプラクティスを説明します。 RESTアプリケーションでの経験をお聞きしたいので、この記事に記載されていないベストプラクティスを知っている場合は、コメントで共有してください。



Disclamer ：すべてのベストプラクティスは私の個人的な経験に基づいています。 別の意見がある場合は、メールでお気軽にお送りください。ご意見をお寄せください。



この記事で説明するベストプラクティスのリストを次に示します。



1. URLのエンドポイント-動詞ではなく名詞

2. 複数

3. ドキュメント

4. アプリケーションのバージョン

5. ページネーション

6. SSLを使用する

7. HTTPメソッド

8. HTTP応答コードの効果的な使用

1. URLのエンドポイント-動詞ではなく名詞

RESTアプリケーション開発者が犯す最も一般的な間違いの1つは、エンドポイントの命名での動詞の使用です。 ただし、これはベストプラクティスではありません。 動詞の代わりに常に名詞を使用する必要があります。



サンプルスクリプト：



インドの農家に関する情報を提供するREST Webサービスを開発するように注文しています。 このサービスには、農家の収入、作物名、農場の住所、各農家に関連するその他の情報などの情報を提供する機能も実装する必要があります。 各農家には一意のIDがあります。



同様に、作物とその所有者に関する情報を提供するサービスを実装する必要があります。



ベストプラクティス：



すべてのアクションを担当する単一のエンドポイントがあります。 以下の例は、追加、更新、削除などのすべての操作に対して1つのエンドポイント/ファーマーのみを示しています。 基本実装には、さまざまな操作に対して正しくルーティングされるさまざまなHTTPメソッドがあります。



•/農家

•/作物



非推奨：



動詞の使用は避けてください。 JSON、XML、RAMLなどの形式内の操作を表すか、HTTPメソッドを使用することをお勧めします。 次の記号は使用しないでください。



•/ getFarmers

•/ updateFarmers

•/ deleteFarmers

•/ getCrops

•/ updateCrops

•/ deleteCrops

2.複数

複数形を使用して、RESTサービスに名前を付けます。 これは、RESTデザイナー間で議論するためのもう1つのホットトピックです。サービスの単一名詞または複数名詞の選択です。



ベストプラクティス：



•/農家

•/農家/ {farmer_id}

•/作物

•/ crops / {crop_id}



非推奨：



•/農家

•/農家/ {farmer_id}



注：

複数形を使用することがベストプラクティスであることに言及しますが、何らかの理由で、単数形に固執する場合は、すべてのサービスでこれに固執します。 複数形と単数形を組み合わせて使用​​しないでください。 したがって、私はここで悪い習慣について話しているのではなく、単にこれはお勧めできないと言っています。 アプリケーションに最適な方法を自分で決定してください。

3.ドキュメント

ソフトウェアのドキュメントは、すべての開発者にとって一般的な慣行です。 RESTアプリケーションを実装するときは、このプラクティスに従う必要があります。 有用なドキュメントを作成すると、他の開発者がコードを理解するのに役立ちます。

RESTアプリケーションをドキュメント化する最も一般的な方法は、エンドポイントがリストされたドキュメントを使用して、それぞれの操作のリストを記述することです。 これを自動的に行うことを可能にする多くのツールがあります。



以下は、RESTサービスの文書化に役立つアプリケーションです。



• DRFドキュメント

• Swagger

• 養蜂場



コメントでアプリケーションを文書化した経験を共有してください。

4.アプリケーションのバージョン

ソフトウェアは時間の経過とともに開発されます。 これには、アプリケーションのすべての主要な変更に異なるバージョンが必要になる場合があります。 アプリケーションのRESTバージョンに関しては、REST開発者コミュニティで最も話題になっているトピックの1つになります。



RESTアプリケーションをバージョン管理するには、2つの一般的な方法があります。



1. URIバージョン。

2.マルチメディアバージョン。



バージョンURI：



URIバージョンがどのように見えるかの簡単な例：

ホスト/ v2 /農家

ホスト/ v1 /農家



URIを使用したバージョン管理方法の主な欠点は次のとおりです。

1. 既存のURIは壊れているため、すべてのクライアントを新しいURIにアップグレードする必要があります。
2. 管理用のバージョンURIの数が増加すると、URIのいくつかのバージョンを格納するためのHTTPキャッシュのサイズが増加します。 多数の重複するURIを追加すると、キャッシュヒットの数に影響する可能性があり、アプリケーションのパフォーマンスが低下する可能性があります。
3. それは非常に柔軟性がなく、リソースまたはそれらの小さなセットを変更することはできません。

マルチメディアバージョン管理方法：

このアプローチでは、各リクエストのヘッダーでバージョン情報を送信します。 マルチメディアURIのタイプと言語を変更するときは、ヘッダーに基づいてコンテンツを見ることに進みます。 この方法は、RESTアプリケーションのバージョン管理に最も適したオプションです。



ヘッダー情報の例：



GET /アカウント/ 5555 HTTP / 1.1

承諾：application / vnd.farmers.v1 + json



HTTP / 1.1 200 OK

コンテンツタイプ：application / vnd.farmers.v1 + json



マルチメディアバージョン管理アプローチでは、クライアントはサーバーに要求するバージョンを選択できます。 この方法はURIアプローチよりも望ましいように見えますが、ヘッダーを介して渡される異なるバージョンの要求をキャッシュする場合に問題が発生します。 簡単に言えば、クライアントがURIに基づいてキャッシュする場合は単純ですが、マルチメディアタイプとしてキーを使用してキャッシュすると複雑さが増します。

5.ページネーション

HTTP経由で大量のデータを送信することはお勧めできません。 確かに、大きなJSONオブジェクトをシリアル化するとコストが高くなるため、パフォーマンスの問題が発生します。 ベストプラクティスは、すべてのレコードを一度に送信するのではなく、結果を部分に分割することです。 前または次のリンクを使用して、ページ上の結果を分割する機能を提供します。



アプリケーションでページネーションを使用する場合、ページネーションリンクを指定する良い方法の1つは、HTTPヘッダーのリンクオプションを使用することです。

次のリンクが役立ちます。

6. SSLを使用する

SSLが必要です！ RESTアプリケーションには常にSSLを使用する必要があります。 アプリケーションへのアクセスは世界中のどこからでも実行され、安全なアクセスが提供されるという保証はありません。 サイバー犯罪に伴うインシデントの増加に伴い、アプリケーションのセキュリティを確保する必要があります。



標準の認証検証プロトコルにより、アプリケーションを簡単に保護できます。 基本認証メカニズムを使用しないでください。 サービスのセキュリティを最大限に高めるには、Oauth1.OaまたはOaurh2を使用します。 最新の機能があるため、個人的にOauth2をお勧めします。

7. HTTPメソッド

すべてのHTTPメソッドの特性を知っていると、HTTPメソッドでの操作の設計が容易になります。 この記事の前のセクションの1つで、操作ごとに異なるサービス名を記述するのではなく、操作にHTTPメソッドを使用することを主張しました。 このセクションでは、主に各HTTPメソッドの動作について説明します。



以下は、HTTPメソッドを使用する前に決定する必要がある2つの特性です。

• セキュリティ：このメソッドを呼び出してもデータの状態が変わらない場合、HTTPメソッドは安全であると見なされます。 たとえば、GETメソッドを使用してデータを取得する場合、このメソッドはサーバー側のデータを更新しないため、安全です。
• べき等性：同じ答えが得られたとき、同じリソースを何回呼び出すかは、べき等として知られています。 たとえば、サーバー上の同じデータを更新しようとすると、同じデータで行われたすべての要求に対して応答が同じになります。

すべてのメソッドが安全でべき等であるとは限りません。 以下は、RESTアプリケーションで使用されるメソッドとそのプロパティのリストです。





REST HTTPメソッド



以下は、各方法の簡単な概要とそれらの使用に関する推奨事項です。

• GET：このメソッドは安全でべき等です。 一般に情報を抽出するために使用され、副作用はありません。
• POST：このメソッドは安全でもべき等でもありません。 この方法は、リソースを作成するために最も一般的に使用されます。
• PUT：このメソッドはべき等です。 そのため、リソースを更新するにはPOSTの代わりにこのメソッドを使用する方が適切です。 リソースを更新するためにPOSTを使用しないでください。
• DELETE：名前が示すように、このメソッドはリソースを削除するために使用されます。 ただし、このメソッドはすべてのクエリでべき等ではありません。
• オプション：このメソッドは、リソースの操作には使用されません。 ただし、クライアントがリソースでサポートされている他のメソッドを知らない場合に役立ちます。このメソッドを使用すると、クライアントはリソースの異なる表現を取得できます。
• HEAD：このメソッドは、サーバーからリソースを要求するために使用されます。 GETメソッドに非常に似ていますが、HEADはリクエストを送信し、ヘッダーでのみレスポンスを受信する必要があります。 HTTP仕様によると、このメソッドはリクエストとレスポンスにボディを使用しないでください。

8. HTTP応答コードの効果的な使用

HTTPはさまざまな応答コードを定義して、操作に関するさまざまな情報をクライアントに示します。 RESTアプリケーションは、利用可能なすべてのHTTPコードを効果的に使用して、クライアントが応答を適切に構成できるようにします。 以下は、HTTP応答コードのリストです。

• 200 OKは、成功したGET、PUT、PATCHまたはDELETEへの応答です。 このコードはPOSTにも使用されますが、作成にはつながりません。
• 201 Created-このステータスコードは、作成につながるPOST応答です。
• 204コンテンツなし。 これは、ボディを返さない成功したリクエストへの応答です（例：DELETEリクエスト）
• 304変更なし— HTTPキャッシュヘッダーが動作しているときにこのステータスコードを使用します。
• 400 Bad Request-このステータスコードは、たとえばボディを分析できない場合など、リクエストの形式が正しくないことを示します
• 401 Unauthorized-認証データが指定されていないか無効である場合。 ブラウザからアプリケーションを使用する場合は、認証ポップアップをアクティブにすることも役立ちます
• 403 Forbidden-認証は成功したが、認証されたユーザーがリソースにアクセスできない場合
• 404 Not found-存在しないリソースが要求された場合
• 405 Method Not Allowed-認証されたユーザーに許可されていないHTTPメソッドが要求されたとき
• 410 Gone-このステータスコードは、このエンドポイントのリソースが利用できなくなったことを示します。 古いAPIバージョンの保護回答として役立ちます。
• 415サポートされていないメディアタイプ。 リクエストの一部として間違ったコンテンツタイプが指定された場合
• 422 Unprocessable Entity-エラーチェックに使用
• 429リクエストが多すぎます-速度制限のためにリクエストが拒否された場合

まとめ

この記事が、独自のREST APIの作成方法を理解するのに役立つことを願っています。 以下は、REST Webサービスアプリケーションに携わった友人との私の経験と議論に基づいて集められたベストプラクティスです。



REST APIの設計に一生懸命取り組んでおり、この記事が意味をなさないと感じた場合は、フィードバックをお聞かせください。 アプリケーションのより良いAPIを開発するためのより実績のある方法でこの議論を更新したいと思います。



良い読書。 ブログをご覧いただきありがとうございます。