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

2007年、Steve JobsはiPhoneを導入しました。これはハイテク業界に革命をもたらし、ビジネスの遂行と遂行に対するアプローチを変えました。 2012年以降、ますます多くのサイトがサービスにネイティブiOSおよびAndroidクライアントを提供しています。 一方、すべてのスタートアップがメイン製品に加えてアプリケーションを開発する資金を持っているわけではありません。 製品の人気を高めるために、これらの企業はサードパーティの開発者が使用できるオープンAPIを提供しています。 おそらくTwitterはこの分野で最初のものであり、現在、この戦略に従っている企業の数は急速に成長しています。 これは、製品の周りに魅力的なエコシステムを作成するための本当に素晴らしい方法です。





スタートアップの人生は変化に満ちており、プロジェクトの運命が決定に依存するターニングポイントです。 コードベースが最も多様な決定の具体化を提供できない場合、あなたは負けます。 サーバーコードは、ビジネスのニーズに短時間で適応するのに十分な柔軟性を備えており、プロジェクトになるかどうかを決定します。 成功するスタートアップは、単に素晴らしいアイデアを提供しただけではなく、質の高い方法でそれを実装することができたスタートアップです。 スタートアップの成功は、製品がiOSアプリケーション、サービス、APIのいずれであるかに関係なく、製品の成功に依存します。 過去3年間、私はWebサービスを使用してiOS（主にスタートアップ向け）のさまざまなアプリケーションに取り組んできました。このブログでは、蓄積された知識をまとめて収集し、RESTful APIを開発する際に従うべき最高のテクニックを紹介しようとしました。 優れたRESTful APIは、簡単かつ簡単に変更できるAPIです。

対象読者

この投稿は、中〜高度なRESTful APIの開発に関する知識をお持ちの方を対象としています。 Java / Ruby / Scalaなどのサーバー言語でのオブジェクト指向（または機能）プログラミングの基本的な知識も必要です。 （PHPまたはProgrammable Hyperlinked Pastaは意図的に無視しました）。

ご注意 あたり ここで、著者は、PHPがProgrammable Hyperlinked Pasta（Programmable Hyperlink Noodles）として解読されたプログラミング言語の歴史に関する半冗談の記事へのリンクを提供しました。 PHPに対する著者の態度の特徴は何でしょうか？

記事の構造と構成

この記事は非常に詳細で、2つの部分で構成されています。 最初はRESTの基本を説明し、2番目はAPIのさまざまなバージョンのドキュメントとサポートを説明します。 初心者向けの前半、プロ向けの後半。 あなたがプロであることは間違いないので、ここで「Documenting API」の章に直接ジャンプするためのリンクを示します。 「多くのbukaf、niasilil ...」のカテゴリからのこの投稿と思われる場合は、おそらくそこから開始する必要があります。

RESTfulの原則

サーバーがRESTの原則に準拠している場合、サーバーはRESTfulと見なすことができます。 主にモバイルデバイスで使用されるAPIを開発する場合、3つの最も重要な原則を理解してそれに従うことは非常に役立ちます。 また、APIの開発中だけでなく、将来のサポートと開発も含まれます。 それでは始めましょう。

無国籍

最初の原則は、国家の独立です。 簡単に言えば、RESTfulサーバーは、クライアントの現在のコンテキスト情報を監視、保存、さらに使用すべきではありません。 一方、クライアントはこのタスクを引き受ける必要があります。 つまり、APIを使用してモバイルデバイスの状態をサーバーに記憶させないでください。



New Facebookというスタートアップがあると想像してみましょう。 開発者が間違いを犯す可能性のある良い例は、モバイルデバイスがストリーム内の最後の読み取り項目を設定できるようにするAPI呼び出しを提供することです（Facebookフィードと呼びましょう）。 通常フィードを返すAPI呼び出し（呼び出し/フィードしましょう）は、設定されたものよりも新しい要素を返すようになりました。 賢いですね。 クライアントとサーバー間のデータ交換を「最適化」しましたか？ しかし、違います。



この場合に問題になる可能性があるのは、ユーザーが2つまたは3つのデバイスからサービスを使用する場合、そのうちの1つが最後に読み取ったアイテムをインストールすると、残りは他のデバイスで読み取ったフィードアイテムをロードできなくなることです以前。



状態の独立性とは、特定のAPI呼び出しによって返されるデータが、以前に行われた呼び出しに依存しないことを意味します。



この呼び出しを最適化する正しい方法は、フィードを返すAPI呼び出しに引数として最後に読み取られたテープエントリが作成された時間を渡すことです（/ feed？LastFeed = 20120228）。 If-Modified-Since HTTPヘッダーを使用する別の、より「正しい」メソッドがあります。 しかし、私たちはまだこの方向には深く入りません。 これについては第2部で説明します。



一方、クライアントは、サーバーにアクセスするときにサーバーで生成されたパラメーターを記憶し（必要）、必要に応じて後続のAPI呼び出しに使用することができます。

キャッシュ可能な階層型アーキテクチャ

2番目の原則は、サーバー応答を一定期間キャッシュし、サーバーへの新しい要求なしで再利用できるという情報をクライアントに提供することです。 このクライアントは、モバイルデバイス自体または中間プロキシサーバーのいずれかです。 キャッシングについては、第2部で詳しく説明します。

クライアント-サーバーのパーティション分割と単一のインターフェース

RESTfulサーバーは、その実装の詳細をできるだけクライアントから隠す必要があります。 クライアントは、どのDBMSがサーバーで使用されているか、または現在リクエストやその他の類似のものを処理しているサーバーの数を知らないはずです。 プロジェクトが急速に人気を博し始めた場合、機能を適切に分離することはスケールアップにとって重要です。



これらは、おそらくRESTfulサーバーの開発中に従うべき3つの最も重要な原則です。 以下に、重要性の低い3つの原則について説明しますが、それらはすべて、ここで話していることに直接関連しています。

RESTリクエストと4つのHTTPメソッド

ゲット

投稿

置く

削除

「キャッシュ可能性」とGETリクエストの原則

覚えておくべき主なことは、GETを介して行われた呼び出しがサーバーの状態を変更しないことです。 これは、リクエストを任意の中間プロキシでキャッシュできることを意味します（負荷削減）。 したがって、サーバー開発者は、データベース内のデータを変更するGETメソッドを公開しないでください。 これは、RESTfulの哲学、特に上記の2番目のポイントに違反しています。 GET呼び出しでaccess.logにエントリを残したり、「最後にログインした」などのデータを更新したりすることはできません。 データベース内のデータを変更する場合は、POST / PUTメソッドである必要があります。

POSTとPUTの同じ議論

HTTP 1.1仕様は、PUTがべき等であることを示しています。 これは、クライアントが1つのURIで多くのPUTリクエストを実行できることを意味し、これにより重複レコードの作成は発生しません。 代入演算は、べき等演算の良い例です

String userId = this.request["USER_ID"];
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

この操作が2回または3回実行されても、害はありません（余分なプロセッササイクルを除く）。 一方、POSTはi等ではありません。 これは少し増加します。 実行されているアクションがべき等であるかどうかを考慮して、POSTまたはPUTを使用する必要があります。 プログラマーの言語では、クライアントが作成されるオブジェクトのURLを知っている場合、PUTを使用します。 クライアントが目的のオブジェクトを作成するメソッド/クラスのURLを知っている場合は、POSTを使用します。

 PUT www.example.com/post/1234
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

クライアントがURIを知っている場合は、PUTを使用します。URI自体はリクエストの結果である可能性があります。 クライアントがこのPUTメソッドを何度も呼び出したとしても、害や重複エントリは作成されません。

 POST www.example.com/createpost
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

サーバー自体が一意の識別子を作成し、それをクライアントに返す場合は、POSTを使用します。 このリクエストが同じパラメータで後で繰り返されると、重複したレコードが作成されます。

この議論の詳細。

DELETEメソッド

DELETEは完全に一意です。 PUTのようなべき等であり、レコードが存在する場合は削除するために使用する必要があります。

RESTの回答

RESTfulサーバーからの応答は、XMLまたはJSON形式として使用できます。 個人的には、同じ応答をXML形式で送信する場合よりも簡潔で、ネットワーク経由で送信されるデータが少ないため、JSONを好みます。 違いは数百キロバイト程度ですが、3Gの速度とモバイルデバイスとの交換の不安定性を考慮すると、これらの数百キロバイトが違いを生む可能性があります。

認証

認証はhttpsで行われ、クライアントは暗号化された形式でパスワードを送信する必要があります。 Objective-CでNSStringハッシュのsha1を取得するプロセスは非常に明確で単純であり、上記のコードはこれを明確に示しています。

 - (NSString *) sha1 { const char *cstr = [self cStringUsingEncoding:NSUTF8StringEncoding]; NSData *data = [NSData dataWithBytes:cstr length:self.length]; uint8_t digest[CC_SHA1_DIGEST_LENGTH]; CC_SHA1(data.bytes, data.length, digest); NSMutableString* output = [NSMutableString stringWithCapacity:CC_SHA1_DIGEST_LENGTH * 2]; for(int i = 0; i <; CC_SHA1_DIGEST_LENGTH; i++) [output appendFormat:@"%02x", digest[i]]; return output; }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

サーバーは、受信したパスワードハッシュをデータベースに保存されているハッシュと比較する必要があります。 いずれにせよ、クライアントからサーバーにパスワードを平文で渡さないでください。 このルールには例外はありません！ パスワードを開いたままにしておくことがユーザーにわかる日は、スタートアップの最終日かもしれません。 一度失われると、信頼を回復することはできません。



RFC 2617は、HTTPサーバーでの認証の2つの方法について説明しています。 最初は基本アクセス、2番目はダイジェストです。 モバイルクライアントの場合、これら2つの方法のいずれかが適切であり、ほとんどのサーバー（およびクライアントも）言語には、このような認証スキームを実装するための組み込みメカニズムがあります。



APIを公開する予定がある場合は、oAuthまたはより優れたoAuth 2.0を検討する必要もあります。 oAuthを使用すると、ユーザーはキー（ログイン/パスワード）を交換することなく、アプリケーションで作成されたコンテンツを他のリソースに公開できます。 また、oAuthを使用すると、ユーザーは正確に使用できるものと、サードパーティのリソースに付与する権限を制御できます。



Facebook Graph APIは、現時点で最も開発され、普及しているoAuthの実装です。 Facebookユーザーは、oAuthを使用して、他の個人情報や識別情報（ユーザー名/パスワード）を公開することなく、サードパーティのアプリケーションと写真を共有できます。 ユーザーは、パスワードを変更することなく、不要なアプリケーションへのアクセスを制限することもできます。



これまで、RESTの基本について説明しました。 次に、記事の本質に目を向けます。 次の章では、文書化、新しいメソッドの作成、APIの古いバージョンのサポートの完了時に使用する実用的な方法について説明します...

APIドキュメント

サーバー開発者が記述できる最悪のドキュメントは、パラメーターの説明と返されたデータを含むAPI呼び出しの長く単調なリストです。 このアプローチの主な問題は、サーバーの変更と、プロジェクトの開発中に返されるデータの形式の変更が悪夢になることです。 この点に関して、クライアントソフトウェア開発者があなたをよりよく理解できるように、いくつかの提案を行います。 時間が経つにつれて、これはサーバーソフトウェア開発者としての開発にも役立ちます。

ドキュメント

アプリケーションが動作するメインの高レベルのデータ構造（モデル）について考えることをお勧めします。 次に、これらのコンポーネントに対して実行できるアクションについて考えます。 foursquare APIドキュメントは、独自のAPIを作成する前に学ぶ良い例です。 これらには、場所、ユーザーなどの高レベルのオブジェクトのセットがあります。 また、これらのオブジェクトに対して実行できる一連のアクションもあります。 製品の高レベルのオブジェクトとそれらに対するアクションを知っているので、API呼び出しの構造を作成することはより簡単で理解しやすくなります。 たとえば、新しい場所を追加するには、/ venues / addなどのメソッドを呼び出すのが論理的です



すべての高レベルオブジェクトを文書化します。 次に、単純なデータ型ではなく、これらの高レベルのオブジェクトを使用して、要求と応答を文書化します。 「この呼び出しは3つの文字列フィールドを返します。最初の呼び出しにはid、2番目の名前、3番目の説明が含まれます」と書き込みます。

クエリパラメータの文書化

ユーザーがFacebokトークンを使用してログインできるAPIがあるとします。 このメソッドを/ loginとして呼び出します。

 Request /login Headers Authorization: Token XXXXX User-Agent: MyGreatApp/1.0 Accept: application/json Accept-Encoding: compress, gzip Parameters Encoding type – application/x-www-form-urlencoded token – “Facebook Auth Token” (mandatory) profileInfo = “json string containing public profile information from Facebook” (optional)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ここで、profileinfoは高レベルのオブジェクトです。 このオブジェクトの内部構造はすでに文書化されているため、このような簡単な言及で十分です。 サーバーが同じAccept、Accept-Encoding、およびEncodingタイプパラメーターを使用している場合、すべてのセクションで繰り返すのではなく、それらをいつでも個別に文書化できます。

応答オプションの文書化

API呼び出しへの応答も、オブジェクトの高レベルモデルに基づいて文書化する必要があります。 同じfoursquareの例を引用して、/ venue /＃venueid＃メソッドを呼び出すと、イベントの場所を説明するデータ構造（モデル）が返されます。



オブジェクト（モデル）の構造を使用してAPIを文書化すると、アイデアの交換、文書化、またはリクエストへの応答で返される内容に関する他の開発者への通知が容易になります。 この章の最も重要な結果は、サーバー側の開発者およびクライアントアプリケーション（iOS / Android / Windows Phone /作成）の開発者として締結する契約としてドキュメントを認識する必要があることです。

APIの新しいバージョンを作成し、古いバージョンのサポートを停止する理由

Web 2.0の時代のモバイルアプリケーションの出現以前は、APIの異なるバージョンを作成することは問題ではありませんでした。 クライアント（JavaScript / AJAXフロントエンド）とサーバーの両方が同時にデプロイされました。 消費者（顧客）は、常に最新バージョンのクライアントソフトウェアを使用してシステムにアクセスしています。 クライアントとサーバーの両方の部分を開発しているのはあなただけなので、APIの使用方法を完全に制御でき、その変更は常にクライアント部分に即座に適用されます。 残念ながら、これは異なるプラットフォーム用に作成されたクライアントアプリケーションでは不可能です。 すべてがうまくいくと信じてAPIバージョン2をデプロイできますが、これは古いバージョンを使用したiOSアプリケーションの動作不能につながります。 App Storeに更新されたバージョンを投稿したにもかかわらず、そのようなアプリケーションを使用しているユーザーがまだいる可能性があるためです。 一部の企業は、プッシュ通知を使用して更新を促すことに頼っています。 これがもたらす唯一のことは、そのようなクライアントの損失です。 100以上のアプリがアップデートを待っている多くのiPhoneを見ました。 あなたが彼らの一人になる可能性は非常に高いです。 APIをバージョンに分割し、必要に応じてその一部のサポートを停止する準備を常に整えておく必要があります。 ただし、APIの各バージョンを少なくとも3か月間維持してください。

バージョニング

サーバーコードを異なるフォルダーにデプロイし、呼び出しに異なるURLを使用しても、APIをバージョンに正常に分割したわけではありません。

したがって、 example.com / api / v1はアプリケーションのバージョン1.0で使用され、最も新しくてクールなバージョン2.0はexample.com/api/v2を使用します



更新を行う場合、ほとんどの場合、内部データ構造とモデルに変更を加えます。 これには、データベースの変更（列の追加または削除）が含まれます。 理解を深めるために、「新しいFacebook」に/ feedというAPI呼び出しがあり、「Feed」オブジェクトを返すとします。 現在、バージョン1では、「リボン」オブジェクトにユーザーアバターURL（avatarURL）、ユーザー名（personName）、投稿テキスト（feedEntryText）、投稿作成時間（timeStamp）が含まれています。 後のバージョン2では、広告主が商品の説明をフィードに投稿できるようにする新しい機能を紹介します。 これで、「リボン」オブジェクトに新しいフィールド「sourceName」が含まれるようになりました。これは、リボンが表示されたときにユーザー名と重複します。 したがって、アプリケーションは「personName」ではなく「sourceName」を表示する必要があります。 「sourceName」が指定されている場合、アプリケーションは「personName」を表示する必要がなくなるため、「sourceName」がある場合は「personName」を送信しないことにします。 これは、アプリケーションの古いバージョンであるバージョン1が更新されたサーバーにアクセスするまで、すべて正常に見えます。 「personName」が欠落しているため、タイトルなしでフィードから広告エントリが表示されます。 このような問題を解決する「有能な」方法は、「personName」と「sourceName」の両方を送信することです。 しかし、友人たち、人生は必ずしもそれほど単純ではありません。 開発者は、オブジェクトの各データモデルでこれまでに行われたすべての単一の変更を追跡することはできません。 半年後にはコードに何かが追加された理由と方法をほとんど忘れてしまうため、これは変更を行うのにあまり効果的な方法ではありません。



Web 2.0に戻ると、これはまったく問題ではありませんでした。 JavaScriptクライアントは、APIへの変更をサポートするためにすぐに修正されました。 ただし、インストールされたiOSアプリケーションはもはやあなたに依存していません。 現在、それらの更新はユーザーの特権です。



この種のトリッキーな状況にはエレガントなソリューションがあります。

URLバージョン管理パラダイム

最初の解決策はURL分離です。

api.example.com/v1/feedsはiOSアプリケーションのバージョン1で使用されますが、

api.example.com/v2/feedsはバージョン2で使用されます。

これは良さそうに聞こえますが、返されるデータの形式が変更されるたびにサーバーコードのコピーを作成し続けることはできません。 このアプローチは、APIがグローバルに変更された場合にのみ使用することをお勧めします。

モデルによるバージョン管理パラダイム

上記では、データ構造（モデル）を文書化する方法を示しました。 このドキュメントは、サーバーパーツとクライアントパーツの開発者間の契約として検討してください。 バージョンを変更せずにモデルを変更しないでください。 つまり、前のケースでは、Feed1とFeed2の2つのモデルがあるはずです。



Feed2にはsourceNameフィールドがあり、sourceNameが設定されている場合、personNameではなくsourceNameを返します。 Feed1の動作は、ドキュメントで指定されているものと同じです。 コントローラーのアルゴリズムは次のようになります。



Factoryメソッドパターンに従って、クラスをインスタンス化するロジックを別のクラスに移動する必要があります。 対応するコントローラーコードは次のようになります。

 Feed myFeedObject = Feed.createFeedObject("1.0"); myFeedObject.populateWithDBObject(FeedDao* feedDaoObject);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

使用されるAPIのバージョンの決定は、リクエストテキストのUserAgentフィールドに従ってコントローラーによって行われます。



追加：

UserAgent文字列のバージョン番号を使用する代わりに、Acceptヘッダーのバージョン番号を使用することをお勧めします。 送信する代わりに

 Accept: application/json
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

送信する必要があります

 Accept: application/myservice.1.0+json
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

したがって、RESTサーバーへのリクエストごとにAPIのバージョンを指定できます。 このヒントを提供してくれたハッカーニュースリーダーに感謝します。



コントローラーは、フィードファクトリメソッドを使用して、バージョンに関するクライアントの要求（すべての要求にはAppName / 1.0のようなUserAgentフィールドが含まれます）からの情報に基づいて、正しいフィードオブジェクト（フィード）を作成します。 この方法でサーバーを設計すると、変更は簡単になります。 変更が既存の契約に違反することはありません。 新しいデータ構造（モデル）を作成し、ファクトリメソッドを変更して、新しいバージョンの新しいモデルのインスタンスを作成するだけです。



このアプローチを使用すると、バージョン1および2のアプリケーションは同じサーバーで引き続き動作できます。 コントローラは、古いクライアントアプリケーション用にバージョン1オブジェクトを作成し、新しいクライアントアプリケーション用にバージョン2オブジェクトを作成できます。

サポート終了

モデルを介してAPIをバージョンに分割するための上記のパラダイムにより、APIのサポートを終了するのがはるかに簡単になります。 これは、APIを公開する最後の段階で非常に重要です。 APIのグローバル更新を行う場合、ビジネスロジックの変更に応じてモデル内のすべてのファクトリメソッドを監査します。



APIのバージョン3のリリース中にバージョン1のサポートを停止することにした場合、対応するモデルを削除し、ファクトリメソッドでインスタンスを作成する行を削除するだけです。 新しいバージョンを作成し、古いバージョンのサポートを停止すると、必ずプロジェクトに付随し、ビジネスが決定する重要な決定をサポートすることがどれほど柔軟かを示します。 急激な変化とターンのできないビジネスは運命づけられています。 通常、重要な変更を加えることができないのは、プロジェクトの技術的な欠陥によるものです。 指定された手法は、このような問題を解決できます。

キャッシング

パフォーマンスに関して注意すべきもう1つの重要な点は、キャッシュです。 これがクライアントアプリケーションのタスクだと思われる場合は、慎重に考えてください。 この記事のパート2では、http 1.1を使用してキャッシュを編成する方法を説明します。

APIのエラー処理と国際化

エラーが発生した場合にエラーの原因をクライアントに伝えることは、正しいデータを送信することと同じくらい重要です。 この記事のパート3では、エラー処理と国際化について説明します。 私は何も約束しません。どんな場合でも、書くのに時間がかかります。



翻訳者から：

私自身はiOSの開発者ではなく、Webサービスも開発していません。この分野での私のレベルは、「初心者になります」と言えます。 しかし、このトピックは私にとって興味深いものであり、私はこの記事が好きだったので、翻訳することにしました。



第二部