みなさんこんにちは！ 私の同僚であるAlign TechnologyのDmitry Pavlovと申します。社内システムの相互作用とサードパーティベンダーとの統合のためのWeb APIを開発しています。 この記事では、Web用のAPI、またはRESTful APIを作成するためのアイデアについてお話します。

近年、Web APIトピックは非常に人気が出てきており、多くの企業が、オープンで内部使用の両方のようなインターフェースを作成しています。 Web APIの説明では、ほとんどの場合、頭字語RESTを見つけることができますが、この用語は何を意味し、正しく使用されていますか？

RESTまたはRESTではない？

ほとんどの開発者、特にロシアでは、RESTがHTTP [S]プロトコルを使用して動作するソフトウェアインターフェースとして理解されており、次の特性があります。

• サーバーはクライアントの状態を保存しません。セッションはなく、リクエストを完了するために必要なものはすべて、リクエスト自体とともにクライアントによって送信されます。

  
  
  
  
  
  
  

• リソースが個別に識別される人間が読めるURL。 これ以上/index.php?productId=1
  
  
  
  ではなく、代わりに/products/1
  
  
  
  使用します

  
  
  
  
  
  
  

• HTTPメソッドの幅広い使用：GETとPOSTに限定されず、PUTとDELETEを追加します。 一部のAPIでは、PATCHも見つけることができます。

  
  
  
  
  
  
  
• データ転送形式として、JSONが使用されます。

通常、このようなAPIが使用されるアルゴリズムは標準です。 まず、ドキュメントを使用してWebサイトにアクセスし、リソースにアクセスするためのURLパターンのリストを含むページを見つける必要があります。 通常、次のようになります。

    API " " --- /recipes/cookies -   , GET   URL     [ { "name" : "   ", "rating" : 5, "shortDescription" : "...." } ] POST   URL     .      json   { "name" : " ", "shortDescription" : "...." ...... } --- /recipes/cookies/:name -     ${name} { "name" : "   ", "rating" : 5, "shortDescription" : "....", "description" : "...." "ingredients" : [ { "name" : "", ..... }, { "name" : "", ..... }, { "name" : "", ..... } ], "cookingSteps" : [ .... ] } //    API   HTTP   URL 
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

そして、それを調べて、リソースにリクエストを行います（通常、これは、指定されたURL形式のパラメーターを置換し、応答を処理するクライアントを作成することで表されます）。

ネットワークのオープンスペースには、このようなAPIの例がたくさんあります。最近まで、Yandexには、このスキームに従って機能するRESTとして宣言された多くのAPI（ 1、2 ）がありました。

主な情報源、つまり ロイ・フィールディングの論文（しばしば参照されますが、あまり読まれません）については、この方法で作成されたAPIは、論文で説明されている原則のいくつかに違反するため、RESTと呼ぶことはできません。最も重要なのはハイパーメディアの使用です状態管理ツール（Hypermedia As The Engine Of Application State、HATEOAS）として、間接的に自己記述メッセージに対処します。

メッセージ内のハイパーメディア

HATEOASの本質は、APIのリソースを記述するためのアプローチです。 クライアントが呼び出すことができるすべての可能な操作のリストを使用して、リソースのセットを単純にリストする代わりに、いくつかの内部ロジックに基づいて、制御の反転を実行します-サーバーはリソースの状態を担当し、リソースに対して現在実行できる操作をクライアントに指示します。 この情報は、クライアントが受信するリソースのまさに表現に存在する必要があります。 したがって、リソースのプレゼンテーション自体は、クライアントがそれで何ができるかを理解するのに十分なほど説明しています。

通常、このアプローチの適用は、クライアントが「エントリポイント」の有限セットを知っていることを意味します（サイトの開始ページに類似しているとみなすことができます）。 。

この目標を達成するために、ハイパーリンクが使用されます。

• すべてのリソースはリンクを使用してアドレス指定可能であり、他のリソースへのリンクはメッセージ自体の中に存在し、相互に通信します。 クライアントは、URI形式に焦点を当てる代わりに、リソースビューに直接配置されたリンクを選択する識別子によってガイドされます。 以前にドキュメントで指摘したように、何らかのIDを取得し、そのIDに基づいて特別なURLを作成する必要があることを指摘したため、URLセットをAPIの一部にすると、URL形成の詳細はサーバーとクライアントの実装に固有のものではなくなりました 最終的に、クライアントはドキュメントのテンプレートからURLを生成するのではなく、リソースにアクセスすることが重要です。
• リソースで利用可能な操作もリンクとして表現できます。

関連するリソースと利用可能なアクションの両方へのリンクがないため、この操作はリソースの現在の状態では利用できません。

ハイパーメディアビューでのCookies Recipes API処理の例

Cookieレシピのディレクトリに関するAPIを使用した例に戻り、それをハイパーメディアビューに変換します。

ご存知のように、レシピのリストと、材料と調理手順をリストした特定のレシピを詳述したリソースがありました。 ハイパーメディアアプローチを使用すると、次のようになります。

 //  { "links": { "self" "/recipes/cookies" } "items": [ { "name": "   ", "rating": 5, "shortDescription": "...." "links": { "self": "/recipes/cookies/   " } } ] } //  { "links": { "self": "/recipes/cookies/   " } "name": "   ", "rating": 5, "shortDescription": "....", "description": "...." "ingredients": [ { "name": "", ..... }, { "name": "", ..... }, { "name": "", ..... } ], "cookingSteps": [ .... ] }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

元のバージョンとの大きな違いは、各リソース内のlinks



オブジェクトの外観です。 このオブジェクトのキーは関係（同じ識別子）であり、値はリンクです。 その結果、レシピカタログから詳細な説明に進む方法に関する追加情報（リソース自体の外部）はリソースに必要ありません。リンクはリソースのプレゼンテーションに組み込まれます。

このアプローチにより、APIの機能を簡単に拡張できます。 各レシピについて、レシピのリストの形式で提示される一連の推奨事項をクライアントに提供するとします。 これは非常に簡単です。リンクオブジェクトに新しいキーを追加するだけです。

 "links" : { "self" : "/recipes/cookies/   ", "http://acme.com/recipes/rels/you-can-also-like" : "/recipes/cookies?related_to=+++" }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

同様に、必要に応じて、成分の識別情報を個別のリソースとして追加することはまったく難しくありません。

API要素はリレーションであるため、URIのコンテンツは何の役割も果たさず、クライアントでの変更なしに、 /recipes/related-to/



または/recipes/234892skfj45sdlkfjdsa12



へのリンクを変更できます

変更サービスのハイパーメディア

ハイパーメディアは、ナビゲーションだけでなくアクションの実行にも使用されますが、リソースに対する特定の操作を実行する責任がある関係を特定し、これらの操作のセマンティクスと詳細を示すだけで十分です。

わかりやすくするために、ハイパーレシピを追加して新しいレシピを作成するAPIの例を検討してください。

 //  { "links" : { "self" : "/recipes/cookies", "http://acme.com/recipes/rels/add-recipe" : "/recipes/cookies" } "items" : [ ..... ] }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

特別な関係を持つリンクを追加しました。 基本的なルールは、クライアントが知らない関係を無視することです。新しいレシピを追加する方法を知らない「古い」顧客は以前と同じように動作しますが、作成をサポートする場合、これはリクエストを送信することで新しいレシピを追加できるというシグナルになりますhttp://acme.com/recipes/rels/add-recipe



に関連して参照されるURI

このアプローチにより、静的な一連の操作とその実装の条件をドキュメントに記述するのではなく、サーバーに直接記述して、クライアントが特定の時間にリソースで実行できる操作とできない操作を制御できます。 新しいアクションを追加することも難しくありません。新しいリレーションを宣言し、サーバーが形成するリソース表現にそれを含め始めるだけです。

もちろん、リンクを提供しても、サーバーがHTTPメソッドを正しく処理し、セマンティクスを監視する責任を免れることはありません:)。

しかし、関係はどうですか？

現時点では、おそらく疑問があります：効果的な仕事のためにクライアントが関係の意味をまだ理解する必要がある場合、これをすべて開始するポイントは何ですか？ それらのドキュメントが必要です。

実際、効果的な仕事のために、クライアントは各関係が何を意味するのかを本当に理解する必要があります。 URIの解釈をリレーションに置き換える背後にある主なアイデアは、リレーションをより永続的にすることです。 URIは実装の詳細であり、時間の経過やサーバーごとに変化する可能性があります。 関係は通信のセマンティックな記述であり、ストレージの詳細とは関係ありません。

レシピを保存するための互換性のあるAPIを作成したいとしますが、ストレージの性質上、各レシピを名前ではなくUUIDで識別したいとします。 元のAPIの場合、これは不可能ですが、ハイパーメディアAPIの場合、クライアントにはまったく見えません。

その結果、サーバー上で変更が行われた場合に変更の影響を受けにくい、より汎用的なクライアントを作成することが可能になります。

ハイパーメディアの種類またはアプリケーション/ jsonが私たちに合わない理由

Hypermediaのアプローチを活用することにしたので、上記の方法でAPIを変更しました。そして、参照によって互いにリンクされたリソースができました。 一見、すべてがAPIの順序どおりになっているように見えるかもしれませんが、Hypermedia APIがあることを宣言する前に、応答で返されるContent-Typeヘッダーを見てみましょう。 そこにapplication/json



またはtext/plain



場合でも、引き続き一生懸命働く必要があります。

機械の目から見たリソース

私たちが持っているリソースを見ると、人々はすぐにリンクを選択し、メッセージの正しい形式の印象を与えます。 メッセージの内容を分析することでこれを終わらせ、これが標準がContent-Type応答ヘッダーを調べることを規定する方法です。

次のサーバー応答を考慮してください。

 200 OK Content-Type: text/plain <?xml version="1.0"?> <hello>world</hello>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

答えにはxml-documentが含まれていることは明らかですが、Content-Typeはコンテンツをプレーンテキストとして認識するように指示しているため、xml-documentは単なる偶然または特殊なケースになります。 そのため、真のContent-Typeが非常に重要です。

どのapplication/json



タスクに適していないのかを理解しましょうか？ 実際、この型を記述する標準は、その型の参照を定義するための場所やメカニズムを提供していません。 また、生成したメッセージにリンクが含まれている場合でも、マシンはそれらをリンクに似た形式のテキストを含む行と区別できません。 ただし、リンクがメッセージのどこにあるか、どこにないかを明確に判断する必要があるため、別のタイプが必要です。

ベンダー固有のタイプ

Content-Typeの正確性の問題を解決する1つの方法は、独自のものを使用することです。 ドキュメントでは、メッセージ内のリンクの場所を明確に示します。 クライアントが私たちの個人的なContent-Typeを使用してサーバーから応答を受け取った場合、もちろん、彼がContent-Typeを理解していない限り、リンクが何であるかを動的に推測する必要はありません。 多くの場合、タイプを説明するドキュメントには、フォーマット自体の詳細（リンクの場所、プロパティの場所）だけでなく、その他の情報も含まれていることに注意してください。

• プロパティのセマンティック記述、つまり ビジネスロジックの観点での意味。
• 要求を送信するために必要なHTTPメソッドなど、クライアントとサーバーの相互作用の詳細。

このようなタイプは、特定のタスクおよび特定の組織用に作成されることが多いため、ベンダー固有と呼ばれます。 IANAに登録する必要はありません。 フォームapplication/vnd.${vendor}+${base_format}



名前を付けることをお勧めしますapplication/vnd.${vendor}+${base_format}



ここで、 ${vendor}



は会社の逆ドメイン、 ${base_format}



はベースとして使用したタイプです。 会社にacme.comドメインがあり、jsonを使用してリソースを表す場合、レシピAPIのタイプ名はapplication/vnd.com.acme.recipes+json



ようになりapplication/vnd.com.acme.recipes+json



。

ハイパーメディアの一般的なタイプ

一見、ベンダー固有のタイプはリンクの問題を解決しますが、独自の問題もあります。

• タイプは相互に互換性がないため、クライアントが複数のAPIと対話する場合、クライアントは多くの異なる実装をサポートする必要があります。 各タイプのフォーマットの解析、プロパティ、リンクなどの強調表示には、個別のライブラリのサポートが必要です。
• 各タスクにベンダー固有のタイプを作成すると、総数が非常に顕著に増加します。

別の方法として、汎用タイプがもたらした新しいアプローチは間もなく登場します。 考えてみると、メッセージ形式に必要なのは、質問に答える仕様だけです。

• リソースのプロパティを見つける方法、
• リソース内のハイパーメディアコントロールを見つける方法。

解決されているのはこの問題です。汎用タイプは特定のドメインドメインに適応しようとせず、処理するリソースのほとんどを記述することができます。

すべてのタイプの汎用の重要な機能は、ドキュメントのセマンティック記述のタスクを引き起こさないことです。 レシピの説明やブログへのコメントなど、それがどのようなリソースであるかを伝えません。これは彼らの仕事ではありません。 形式の詳細を担当し、セマンティック仕様をそのまま使用できます。 セマンティクスは、いわゆるプロファイル（プロパティと関係（リレーション）のセマンティクスを説明する別個の文書）で囲まれることが想定されています。

現時点では、そのようなフォーマットはすでにかなり多数あるため、そのうちのいくつかをリストします。

• application/hal+json
  
  
  
  最近登場したものの1つであり、最近最も人気のある形式です。
• application/vnd.siren+json
  
  
  
  ;
• application/mason+json
  
  
  
  。

このようなすべての形式の説明には、リソースのプロパティを配置する方法と場所、他のリソースへのリンクを作成する形式が記載されています。

タイプ自体に含まれる形式と機能が異なります。

クリエイターの形式や原則の違い

ほとんどの汎用タイプには、リンクのフォーマット方法など、細かい部分があります。 そのため、HALでは、リンクは次のようになります。

 "_links" : { "self" : .... "relToResource": ..... }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

一方、Sirenは次のように表示します。

 "links" : [ {"rel" : ["self"], "href" : "...."}, {"rel" : ["relToResource"], "href" : "...."} ]
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ここでの主な違いは、関係値の表現です。 HALの作成者はフォーマットをより簡潔にしたかったのに対し、Sirenの作成者はそれをより完全なものにしたかったのです。リンクではリレーションが本当に複雑になる可能性があります（これがSirenの値の配列である理由です）が、これは常に使用されるわけではありませんオブジェクト内）。

このようなさまざまなビューにより、さまざまな形式が作成され、単一の形式に同意することはできませんでした。

機会の違い

ここでは、フォーマットのすべての違いをリストするのではなく、すでに述べたタイプを例として使用して、主なもののみを概説します。

• HALには、独立したエンティティとしてのアクションの概念はありません。リクエストの送信に使用する必要があるリンクとメソッドのみがメッセージに含まれていません。 SirenとMasonには、フォームを記述するためのツールがあります。メッセージには、クライアントによる入力に必要なパラメーター、これをすべて送信する必要があるメソッド、およびContent-Typeが含まれます。
• HALには、検索フォームという別の概念があります。これは、サーバーから情報を受信するための安全でべき等なアクションです。 サイレンとメイソンは、前述のように、あらゆるアクションを記述する能力を持っています。
• HALとSirenには、仕様にエラーの説明の詳細が含まれていません。これは、フォーマットのユーザーの裁量に留まります（ application/vnd.error+json
  
  
  
  使用できます） application/vnd.error+json
  
  
  
  では、この側面はフォーマットに含まれます。

汎用とベンダー固有

どちらのオプションが望ましいか：特別に作成されたタイプか、既存のオプションの1つですか？ 通常、同様の質問の場合と同様に、それに対する明確な答えはありません。すべては使用状況に依存するため、それぞれの利点と欠点を強調してみましょう。

汎用ハイパーメディアタイプの主な利点の1つは、ユーザーとAPIクライアントの時間を節約できることです。 それはそれを通して達成されるものです：

• メッセージ形式はすでに開発されています。 選択した形式の既に確立された制限でAPIを作成することにより、問題の解決に集中できます。
• メッセージを作成および解析するために、さまざまなプログラミング言語用のライブラリがすでに作成されています。 既成のライブラリを接続して、JSONのパスの詳細ではなく、リンク、アクション、オブジェクトプロパティなどの高レベルの概念を操作すると便利です。
• 多くの一般的なタイプには、いわゆるブラウザーがあります。 これらは、特定のタイプの要素を理解し、Webインターフェースを動的に形成する単純なクライアントです。これにより、クライアントの作成に1分も費やすことなく、作成されたAPIをすぐに実証できます。
• 顧客は、APIのドキュメント、つまり フォーマットの詳細を読む時間を費やすことなく、ビジネス感覚にのみ集中できます。

同時に、このアプローチの利点のいくつかは欠点のように見えるかもしれません。 この型はどのドメイン領域やタスクにも結び付けられていないため、作成できる特殊な型と比較して、リソースの表現はより「肥大化」しています。

その結果、ほとんどのタスクで、デフォルトの汎用ハイパーメディア形式のいずれかを使用することをお勧めし、複雑または特定のケースでベンダー形式を選択できます（もちろん、ベンダーロックインの目標を設定しない限り）。

これはどれくらい必要ですか？

説明したアプローチは、APIの開発におけるすべての問題を解決するために設計された別の特効薬ではありません。

エントリポイントの概念は、目的のリソースに「到達」するためのリクエスト数の増加につながる可能性があり、リンクを含めて、ベアデータと比較してメッセージをより多くすることに注意できます。

これらの問題は、よく考え抜かれたリソース構造（クイックナビゲーションのエントリポイントでリソース検索操作を実行できないのは誰ですか）、キャッシング（このアーキテクチャアプローチの重要なコンポーネントとしてフィールディングでも指摘されている）、およびWebサーバーでの圧縮の通常の包含によって解決されるというこれらの欠点に反対することができます。

RESTが提供する柔軟性と拡張性におけるRESTアプローチ（ここでは完全なREST）の主な利点は、既存のクライアントの作業を中断することなく、サーバー上のリソースの構成を変更したり、新しい機能を追加したりできることです。

APIでハイパーメディアを使用しないことにした場合でも、それなしではRESTはRESTではなく、単なるWeb APIであることがわかります。 これはAPIを良いものにも悪いものにもせず、事実を述べているだけです。 , API API, , :).

• API — hypermedia API, HAL.
• Github — ( JSON), hypermedia.
• Paypal .
• Foxycart — API — HAL Siren.
  
  ( , opensource)