サーバー用のRESTful API-正しく実行する（パート2）

記事の最初の部分では 、RESTfulの原理を簡単に説明し、新しいものを簡単にリリースしてAPIの古いバージョンのサポートを停止できるようにサーバーアーキテクチャを設計する方法を説明しました。 このパートでは、HATEOASとHypermediaについて簡単に説明し、次にモバイルデバイス用のネイティブアプリケーションの開発で果たすことができる役割について説明します。 ただし、この記事の主なトピックは、キャッシュの実装（より正確には、サーバー側でのキャッシュのサポート）です。 対象読者には、サーバーソフトウェアの開発者と、ある程度iOSまたはその他のモバイルプラットフォームの開発者が含まれます。

HTTP API、REST、およびHATEOAS

現在、HTTP APIは次のように分類できます。

• Webサービス
• RPC URIトンネリング
• HTTPベースのタイプ1
• HTTPベースのタイプ2
• REST

これについては 、Jon Algermissenによる非常に良い説明があります。 残念ながら、APIを提供する人は誰でもRESTfulサービスを呼び出します。

それでは、本当のRESTfulサーバーとは何でしょうか？ これは、ハイパーテキスト/ハイパーメディアベースのAPIです。 つまり、サードパーティの開発者またはクライアントアプリケーションは、ルートAPI URLを介して「他の利用可能なリソース」に関する情報を取得できる必要があります。 これは、RESTful APIを実装する際に実際に最も重要な条件です。 また、HATEOASの原則に準拠しているもののみが、実際のRESTfulサーバーと見なすことができます。

HATEOAS-アプリケーション状態のエンジンとしてのハイパーメディア

HATEOASを実装する際に従うべき2つの主な原則は次のとおりです。

1. ハイパーメディアリソースのみをサービスします。 ハイパーリンクリソースは、コンテンツと他のハイパーリンクリソースへのハイパーリンクのみを含むリソースです。 JSON（application / json）はハイパーリンクリソースではありません。 （一方で、JSONをサポートするRESTfulのHATEOASサーバーが多数あります）ただし、追加のフィールドをJSONに追加して、JSONをハイパーリンクリソースとして機能させることができます。 （例：対応する画像サムネイルへのリンクのhrefフィールド）
2. クライアントアプリケーションの単一のエントリポイント。 APIホームページから、後続のGET呼び出しを対応するURLへのリンクとして、また後続の「POST」、「PUT」または「DELETE」リクエストをフォームの形式で作成する必要があります。

これらの2つのHATEOASの原則に従うことで得られる主な利点は、文書化の容易さです。

新しいAPIでHATEOASを使用していますか？

いや！

なんで？ これまで、APIはほとんどがWebアプリケーションで使用するために作成されていました。 これらのサーバーは通常XHTMLを返し、クライアントアプリケーションはブラウザーで実行されました。 このようなスキームのブラウザは、モバイルクライアントに似ています。モバイルクライアントは、ハイパーリンクリソースを解析し、フォームが何であるかと、それをユーザーに提示する方法を知っています。 モバイルアプリケーションの場合、RESTfulサーバーの応答に、サーバーにデータを送信できるフォームが含まれている場合、プラットフォームで使用可能なネイティブインターフェイス要素に変換することはできません（少なくとも余分な労力なしで）。 Apple / GoogleまたはMicrosoftのいずれのプラットフォームプロバイダーも、XHTMLフォームをUIViewController（iOS）またはIntent（Android）またはSilverlight Page（Windows Phone）に変換することをサポートしていません。 GETリクエストへの応答としてハイパーリンクリソースの出力を使用し、すべてのPOST / PUTおよびDELETEリクエストに対して（フォームの代わりに）コントローラーメソッドへの呼び出しを提供することをお勧めします。 （例：/友人/追加または/会場/チェックイン）コントローラーメソッドへの呼び出しは、他の回答に埋め込むことができます（クライアントアプリケーションまたは開発者がそれらについて知ることができるように）。 もちろん、これはRESTの原則に違反しますが、それでもかまいません。 実際にはほとんど役に立たない標準に盲目的に従うよりも、高品質の製品を作る方が良い。 （これにより、おそらくAPIがHTTPベースのタイプ2になります）。

キャッシング

キャッシングに渡します。 多くの人が信じているように、キャッシュは基本的にクライアントタスク（または中間プロキシタスク）です。 しかし、サーバー側の開発にほとんど労力を費やすことなく、APIを中間キャッシングプロキシの要件に完全に適合させることができることを知っていますか？ つまり、無料のロードバランシングを受け取ることになります。 必要なものは、HTTP仕様の第13章で説明されています 。



少し前、アートテイラーはツイートしました。



「2つの新しいルールを思い付きました。1）アプリケーションの速度が低下した場合は、キャッシュを追加します。2）アプリケーションにバグがある場合は、キャッシュを削除します。



しかし、信じてください、キャッシングはそのような問題に遭遇することなく実装できます。 従うことをお勧めする2つの主な原則は次のとおりです。

1. クライアントアプリケーションでカスタムキャッシュスキームを作成しようとしないでください。
2. RFC HTTP 1.1仕様で説明されている基本的なキャッシュ原則を理解してください。 そこで2つのキャッシュモデルが説明されています。 妥当性モデルと妥当性モデル。

クライアントサーバーアプリケーションでは、サーバーは信頼できる情報源です。 サーバーのAPIからリソース（ページまたは応答）をダウンロードすると、サーバーはクライアントに、特にクライアントが受信したリソースをキャッシュする方法に関する追加の「ヒント」を送信します。 サーバーは、キャッシュされた情報の有効期限が切れそうになると、クライアントに正式に通知します。 これらのプロンプトは、プログラムとサーバー構成の両方で送信できます。 有効期限モデルは通常、サーバーの構成を通じて実装されますが、有効性モデルにはサーバー側の開発者によるソフトウェア実装が必要です。 有効期間をいつ使用するか、有効期間は返されるリソースのタイプに基づいて決定するのは開発者です。 通常、有効期限モデルは、特定のリソースの有効期間をサーバーが明確に決定できる場合に使用されます。 有効性モデルは、他のすべての場合に使用されます。 後で、サーバー開発中にこれらのモデルの両方を実装する方法を示します。 両方に対処したらすぐに、それぞれを使用するタイミングを示します。

有効期限モデル

一般的なキャッシング構成を見てみましょう。 nginxを使用する場合、おそらく設定に類似したものがあります。

location ~ \.(jpg|gif|png|ico|jpeg|css|swf)$ { expires 7d; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

nginxはこれらの設定を適切なHTTPヘッダーに変換します。 この場合、サーバーはすべての画像のヘッダーで「Expires」または「Cache-Control：max-age = n」フィールドを送信し、クライアントがそれらを7日間キャッシュすることを想定しています。 これは、今後7日間同じデータを要求する必要がないことを意味します。 一般的なブラウザ（および中間プロキシ）はそれぞれ、このヘッダーを尊重し、期待どおりに機能します。 残念ながら、人気のあるSDWebImageを含むiOS用のほとんどのオープンソース画像キャッシュフレームワークは、n日後に画像を単に削除する組み込みのキャッシュメカニズムを使用します。 問題は、そのようなフレームワークが妥当性モデルに対応せず、これらのフレームワークを使用するクライアントアプリケーションが非標準ソリューション（ハック）に頼らざるを得ないことです。 ここで何がうまくいかないかを示す例を示します。 「新しいFacebook」に戻りましょう。 ユーザーがサーバーにアバターをアップロードするとき、ユーザーは変更がすべてのビューに反映されると信じています。 いくつかのトリッキーな開発者は、update-profile-image呼び出しの成功後にローカルキャッシュをクリアします。 （これは、すべてのコントローラーが新しい方法でサーバーから画像をダウンロードする必要があることを意味します）。 すべてがうまく機能し、プロジェクトマネージャーに報告すると、各ビューで最新のプロフィール画像が表示されます。 ただし、これで問題が完全に解決されるわけではありません。 彼の友人は、ユーザーの新しいアバターを7日後に表示します。 絶対に受け入れられません。 それでこれを解決する方法は？ 先ほど言ったように、サーバーだけが信頼できるデータのソースになることができるという声明を受け入れなければなりません。 キャッシュされたコンテンツを早期に期限切れにしてキャッシュを更新するために、クライアントで不正なトリックを使用しないでください。

妥当性モデル

FacebookとTwitterは、有効性モデルを使用して、（新しい画像がアップロードされた後の）古いプロファイル画像の問題を解決します。 妥当性モデルでは、サーバーは一意のリソース識別子をクライアントに送信し、クライアントは識別子と応答の両方をキャッシュします。 HTTPに関しては、この一意の識別子はETagと呼ばれます。 同じリソースに対して2番目のリクエストを行う場合、それをETagに送信する必要があります。 サーバーはこの識別子を使用して、要求したリソースが最後の呼び出し以降に変更されたかどうかを確認します（サーバーは唯一の信頼できるソースであることに注意してください）。 リソースが実際に変更された場合、最後のコピーを送信します。 それ以外の場合、304 Not Modifiedを送信します。 キャッシュの有効性モデルでは、クライアントとサーバーの両方の部分を実装してキャッシュを実装するために、開発者がさらに努力する必要があります。 両方についてさらに説明します。

カスタマーサポート

実際iOSでは、MKNetworkKitを使用すると、すべての作業が自動的に行われます。 しかし、AndroidおよびWindows Phoneの開発者向けに、これをどのように実装するかを詳細に説明します。

キャッシュ有効性モデルは、ETagおよびLast-Modoified HTTPヘッダーを使用します。 クライアント側の実装は、サーバー側よりも簡単です。 リソースを含むETagを受け取った場合、それを受け取るための2番目の要求を行うときに、ヘッダーの「IF-NONE-MATCH」フィールドにETagを送信します。 同様に、リソースで「Last-Modified」を受信した場合、後続のリクエストで「IF-MODOFIED-SINCE」ヘッダーに送信します。 サーバーは、「ETag」をいつ使用し、「Last-Modified」を使用するかを決定します。







有効期限モデルの実装は簡単です。 ヘッダーフィールド「Expires」または「Cache-Control：max-age-n」に基づいて有効期限を計算し、この日付に達するとキャッシュをクリアします。

サーバー側の実装

ETagを使用する

ETagは通常、ハッシュアルゴリズムを使用してサーバー上で計算されます。 （Java / C＃/ Scalaなどのほとんどの高レベルサーバー言語には、オブジェクトをハッシュする機能があります）。 応答を生成する前に、サーバーはオブジェクトのハッシュを計算し、それをETagヘッダーフィールドに追加する必要があります。 クライアントが実際にリクエストでIF-NONE-MATCHを送信し、このETagが計算した値と等しい場合、304 Not Modifiedを送信します。 それ以外の場合は、応答を作成し、新しいETagで送信します。



最終変更の使用

Last-Modifiedの使用を実装することは、完全に簡単ではありません。 APIに友人のリストを返す呼び出しがあることを想像してみましょう。

 http://api.mynextfacebook.com/friends/
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ETagを使用すると、友人の配列のハッシュを計算します。 Last-Modifiedを使用する場合、リソースが最後に変更された日付を送信する必要があります。 このリソースはリストであるため、この日付は最後に新しい友達を追加した日付である必要があります。 これには、開発者がデータベース内の各ユーザーの最後のデータ変更の日付を整理する必要があります。 ETagより少し複雑ですが、パフォーマンスの面で大きな利点があります。

クライアントが初めてリソースを要求するときに、友達の完全なリストを送信します。 クライアントからの後続のリクエストには、ヘッダーに「IF-MODIFIED-SINCE」フィールドが含まれるようになります。 サーバーコードは、指定した日付以降に追加された友達のリストのみを送信する必要があります。 変更前のデータベースにアクセスするためのコードは次のようなものでした：

 SELECT * FROM Friends;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

変更後、次のようになりました。

 SELECT * FROM Friends WHERE friendedDate > IF-MODIFIED-SINCE;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

要求がレコードを返さない場合、304 Not Modifiedを送信します。 したがって、ユーザーに300人の友人がいて、そのうち2人だけが最近追加された場合、回答には2つのエントリのみが含まれます。 リクエストのサーバー処理時間と同時に消費されるリソースが大幅に削減されます。

もちろん、これは非常に単純化されたコードです。 友人の削除またはブロックをサポートすることにした場合、開発者に頭痛が追加されます。 サーバーはヒントを送信できる必要があります。このヒントを使用して、クライアントはどの友達が追加され、どの友達が削除されたかを伝えることができます。 この手法では、サーバー側の開発に追加の労力が必要です。

キャッシングモデルの選択

だから。 難しいトピックでした。 次に、特定のキャッシュモデルを使用するための基本的なルールをまとめて導き出します。

1. すべての静止画像は、有効期限モデルによって提供される必要があります。
2. 動的に生成されたすべてのデータは、妥当性モデルによってキャッシュされる必要があります。
3. 動的に生成されたリソースがリストである場合、Last-Modified妥当性モデルを使用する必要があります。 （例：/友達）。 その他の場合、ETagベースの妥当性モデルを使用する必要があります。 （例：/friends/firstname.lastname）。
4. ユーザーが変更できる画像やその他のリソース（アバターなど）も、ETagを使用した妥当性モデルによってキャッシュする必要があります。 これらは画像ですが、会社のロゴのように永続的ではありません。 また、そのようなリソースの有効期間を正確に計算することはできません。

別の方法（実装は簡単ですが、少しハッキング）は、「URLエラー」を使用することです。 回答にアバターURLがある場合、その一部を動的にする必要があります。 そのため、URLを次のように表す代わりに

 http://images.mynextfacebook.com/person/firstname.lastname/avatar
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

する

 http://images.mynextfacebook.com/person/firstname.lastname/avatar/<>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ユーザーがアバターを変更すると、ハッシュも変更されるはずです。 友達リストを送信するコールは、アバターを変更したユーザーに変更されたURLを送信するようになりました。 したがって、プロファイル画像の変更はほぼ瞬時に配信されます！

サーバーアプリケーションとクライアントアプリケーションが実際に確立されたキャッシュ標準を満たしている場合、iOSアプリケーションと製品は一般に「飛ぶ」だけです。



この記事では、ほとんどの開発者が順守していない標準について簡単に説明しました。



これで、記事の第2部は終わりです。 以下および最後では、エラーとその適切な処理に関する情報の交換、およびアプリケーションの国際化について説明します。

読むことをお勧めします

REST API設計ルールブック