👩🏼‍🚒 💭 👨‍🎤 JSON API-仕様に従って動作します 🛀🏽 💴 🔥

最近、Web開発が分割されました。現在、私たちはすべてフルスタックのプログラマーではありません-フロントエンドおよびバックエンドです。そして、これで最も難しいことは、他の場所と同様に、相互作用と統合の問題です。

フロントエンドとバックエンドは、APIを介して対話します。そして、全体の開発結果は、それがどのAPIであるか、バックエンドとフロントエンドがどれだけ良いか悪いかに同意したかによって異なります。アップグレードを行う方法について全員で話し合い、1日中作業をやり直すと、ビジネスタスクに到達できなくなる可能性があります。

変数の名前についてホリバーを失速させたり繁殖させたりしないためには、適切な仕様が必要です。誰にとっても人生を楽にするためにどうあるべきかについて話しましょう。同時に、自転車小屋の専門家になります。

遠くから始めましょう-私たちが解決しようとしている問題で。

昔、1959年に、シリルパーキンソン（病気と混同しないでください、彼は作家であり経済学者です）はいくつかの興味深い法律を思いつきました。たとえば、その費用は収入などとともに増加します。それらの1つは自明の法則と呼ばれます：

アイテムの議論に費やされる時間は、考慮される量に反比例します。

パーキンソンは経済学者だったので、彼は自分の法律を経済的な観点から次のように説明しました。取締役会に来て、原子力発電所を建設するために1000万ドルが必要だと言った場合、おそらくこの問題は、従業員用の自転車小屋に100ポンドを割り当てるよりもはるかに少ない議論になるでしょう。誰もが自転車小屋の作り方を知っているため、誰もが自分の意見を持ち、誰もが重要だと感じ、参加したいと思っています。原子力発電所は抽象的で遠いものであり、1000万人も見たことがない-質問はほとんどありません。

1999年、パーキンソンの自明の法則がプログラミングに登場し、その後積極的に開発されました。プログラミングでは、この法律は主に英語の文学で発見され、比likeのように聞こえました。自転車小屋効果（自転車小屋の効果）と呼ばれていましたが、本質は同じです-自転車小屋の準備ができており、発電所の建設よりもずっと長い間議論したいと思います。

この用語は、FreeBSDの作成に関与したデンマークの開発者Poul-Henning Kampによって作成されました。設計プロセス中に、チームは非常に長い間、スリープ機能がどのように機能するかを議論しました。これは、Poul-Henning Kampからの手紙からの引用です（開発はその後、電子メールで行われました）。

スリープ（1）DTRTにするという提案でした。この特定の草の火を消す非整数の引数が与えられた場合、それ以上のことは言わないでしょう。スレッドの長さを期待し、この問題のいくつかよりもはるかに多くの注意をすでに受けています。

この手紙の中で、彼はもっと多くの重要な未解決の問題があると言います。「自転車小屋を取り扱わないで、それについて何かをして先に進みましょう！」

そのため、1999年にPoul-Henning Kampは、自転車文献という用語を英語の文学に導入しました。

コードの変更によって作成されるノイズの量は、変更の複雑さに反比例します。

追加または変更が単純になるほど、それについて多くの意見を聞く必要があります。多くの人がこれに会ったと思います。たとえば、変数に名前を付ける方法などの簡単な質問を解決する場合、マシンにとっては問題になりません。この質問は膨大な数のホリバーを引き起こします。しかし、深刻で、ビジネス上の問題にとって本当に重要なことは議論されず、バックグラウンドで行われます。

もっと重要だと思うのは、バックエンドとフロントエンドの間でやり取りする方法、または私たちが行うビジネスタスクですか？誰もが異なる考えを持っていますが、お金をあなたに持って来ることを期待している顧客は、「私たちのビジネスタスクをもうやってくれ！」と言います。バックエンドとフロントエンドの間でデータを転送する方法は重要ではありません。おそらく彼はバックエンドとフロントエンドが何であるかさえ知らないでしょう。

導入をまとめると、 APIは自転車置き場です。

プレゼンテーション リンク

講演者について： Alexey Avdeev（Avdeev）はNeuron.Digital社で働いています。Neuron.Digitalはニューロンを扱い、それらのクールなフロントエンドを作成しています。また、AlexはOpenSourceに注意を払い、すべての人にアドバイスしています。彼は長い間開発に携わっています-2002年以来、彼は古代のインターネットを発見しました。コンピューターが大きく、インターネットが小さく、JSの欠如は誰も気にしませんでした。

自転車小屋に対処する方法は？

尊敬されるシリル・パーキンソンが些細な法則を推論した後、彼は多くの議論をされました。ここでは、自転車小屋の影響を簡単に回避できることがわかります。

アドバイスを聞かないでください。 アイデアはまあまあだと思います。アドバイスに耳を傾けなければ、特にプログラミングで、特に初心者開発者であれば、それをたくさん作ることができます。
あなたが望むようにしてください。 「私はアーティストです、そうですね！」-バイクシェッド効果はありません。必要なものはすべて実行されますが、出力には非常に奇妙なことが表示されます。これはしばしばフリーランスで見られます。確かに、他の開発者のために完了しなければならないタスクに出くわし、その実装はあなたを当惑させました。
自問することは重要ですか？ そうでなければ、あなたは単にそれを議論することはできませんが、それは個人的な意識の問題です。
客観的な基準を使用します。 この点についてはレポートでお話しします。自転車小屋の影響を避けるために、客観的にどちらが良いかを判断する基準を使用できます。それらが存在します。
アドバイスを聞きたくないことについては話さないでください。 私たちの会社では、最初のバックエンド開発者は内向的であるため、他の人に伝えないようなことをすることがあります。その結果、私たちは驚きに出会います。この方法は機能しますが、プログラミングでは最適なオプションではありません。
問題を気にしない場合は、そのままにするか、ホリバーの過程で生じた提案されたオプションのいずれかを選択できます 。

自転車脱落防止ツール

自転車小屋の問題を解決するための客観的なツールについて話したいです。自転車脱落防止ツールが何であるかを示すために、少し話をします。

初心者のバックエンド開発者がいると想像してください。彼は最近入社し、小さなサービス（ブログなど）の設計を依頼されました。そのためにはRESTプロトコルを作成する必要があります。

ロイフィールディング、RESTの著者

写真では、2000年に彼の論文「建築様式とネットワークソフトウェアアーキテクチャの設計」を擁護したRoy Fieldingが、RESTという用語を導入しました。さらに、彼はHTTPを発明し、実際、インターネットの創設者の1人です。

RESTは、RESTプロトコル、REST API、RESTfulサービスの設計方法を示す一連のアーキテクチャ原則です。これらは非常に抽象的で複雑なアーキテクチャの原則です。 RESTfulのすべての原則に完全に準拠したAPIを見たことのある人は誰もいないと確信しています。

RESTアーキテクチャーの要件

RESTプロトコルのいくつかの要件を示します。これらの要件を参照し、それらに依存します。それらのかなりの数があります、あなたはウィキペディアでそれについてもっと読むことができます。

1. クライアントサーバーモデル。

RESTの最も重要な原則、つまりバックエンドとの対話。 RESTによれば、バックエンドはサーバーであり、フロントエンドはクライアントであり、クライアントとサーバーの形式で通信します。モバイルデバイスもクライアントです。時計、冷蔵庫、その他のサービスの開発者もクライアント部分を開発します。 RESTful APIは、クライアントがアクセスするサーバーです。

2. 状態の欠如。

サーバーには状態が存在しないようにする必要があります。つまり、応答に必要なものはすべて要求に含まれます。セッションがサーバーに保存され、このセッションに応じて異なる回答が来る場合、これはRESTの原則に違反しています。

3. インターフェースの均一性。

これは、REST APIを構築する上で重要な基本原則の1つです。次のものが含まれます。

リソースの識別は、URLを構築する方法です。 RESTでは、何らかのリソースをサーバーに求めます。
プレゼンテーションによるリソースの操作。サーバーは、データベースにあるビューとは異なるビューを返します。情報をMySQLに保存するかPostgreSQLに保存するかは問題ではありません。ビューがあります。
「自己記述型」メッセージ-つまり、メッセージにはid、このメッセージを再度取得できるリンクが含まれます-このリソースを再度使用するために必要なすべてのことです。
ハイパーメディアは、リソースを使用した以下のアクションへのリンクです。単一のREST APIがそれを行うわけではないようですが、それはRoy Fieldingによって記述されています。

私の話には重要ではないので、引用しない原則が3つあります。

RESTfulブログ

最初のバックエンド開発者に戻り、RESTfulでブログのサービスを作成するよう依頼されました。以下はプロトタイプの例です。

これは記事があるサイトで、あなたはそれらにコメントすることができます、記事とコメントには著者がいます-標準的な物語。初心者のバックエンド開発者は、このブログのRESTful APIを実行します。

CRUDに基づいてすべてのブログデータを処理します。

リソースを作成、読み取り、更新、および削除できる必要があります。バックエンド開発者に、CRUDの原理に基づいてRESTful APを構築するよう依頼してみましょう。つまり、記事を作成するメソッド、記事のリストまたは単一の記事を取得するメソッド、更新および削除するメソッドを記述します。

彼がそれをどうやってできるか見てみましょう。

ここでは、RESTのすべての原則に関してすべてが間違っています 。最も興味深いのは、機能することです。実際にこのようなAPIを入手しました。顧客にとっては自転車置き場であり、開発者にとっては冷静に議論する機会であり、初心者の開発者にとっては、毎回つまずき、転倒して頭を打ち砕く巨大で勇敢な新しい世界です。彼は何度も何度もやり直さなければなりません。

これはRESTオプションです。リソースを識別するという原則に基づいて、私たちはリソースを使用し、記事を作成し、Roy Fieldingが提案したHTTPメソッドを使用します。彼は彼の前の作品を次の作品で使用せざるを得なかった。

記事を更新するために、多くの人がPUTメソッドを使用していますが、セマンティクスが少し異なります。 PATCHメソッドは渡されたフィールドを更新し、PUTは単に1つの記事を別の記事に置き換えます。セマンティクスにより、PATCHはマージであり、PUTは置換です。

私たちの初心者バックエンド開発者は落ちて、彼らはそれを拾い上げて言った：「すべてが順調で、それをそのようにしてください」そして彼は正直にそれをやり直した。しかし、その後、彼はとげを介して巨大な長い道を見つけるでしょう。

なぜそんなに正しいのですか？

ロイ・フィールディングがそう言ったからです。
RESTであるため。
これらは私たちの職業が現在基づいているアーキテクチャの原則だからです。

ただし、これは「自転車置き場」であり、以前の方法は機能します。コンピューターはRESTの前に通信し、すべてが機能しました。しかし、今では業界に標準が登場しています。

記事を削除する

記事を削除する例を考えてみましょう。 IDで記事を削除する通常のリソースメソッドDELETE / articlesがあるとします。 HTTPにはヘッダーが含まれます。 Acceptヘッダーは、クライアントが応答として受信するデータのタイプを受け入れます。私たちの後輩は、200 OK、Content-Type：application / jsonを返し、空のボディを渡すサーバーを作成しました。

01. DELETE /articles/ 1 /1.1 
      

        
        
        
      

     02. Accept: application/json

01. HTTP/1.1 200 OK 
      

        
        
        
      

     02. Content-Type: application/json 
      

        
        
        
      

     03. null

ここで非常に一般的な間違いがありました-空の体 。すべてが論理的なようです-記事は削除され、200 OK、application / jsonヘッダーは存在しますが、クライアントはおそらく落ちます。空のボディが有効ではないため、エラーがスローされます。空の文字列を解析しようとしたことがあると、jsonパーサーがつまずいてクラッシュするという事実に直面します。

この状況を修正するにはどうすればよいですか？おそらく最良のオプションはjsonを渡すことです。「承諾、jsonを提供」と述べた場合、サーバーは「Content-Type、jsonを提供」、jsonを提供します。空のオブジェクト、空の配列-そこに何かを置く-これが解決策となり、動作します。

まだ解決策があります。 200 OKに加えて、応答コード204があります-コンテンツはありません。それを使用すると、体を送信することはできません。誰もがこれについて知っているわけではありません。

だから私はメディアの種類につながった。

MIMEタイプ

メディアタイプはファイル拡張子のようなもので、Web上でのみ使用できます。データを送信する場合、応答として受信するタイプを通知または要求する必要があります。

デフォルトでは、これはテキスト/プレーン-単なるテキストです。
何も指定されていない場合、ブラウザはおそらくアプリケーション/オクテットストリーム-単なるビットストリームを意味します。

特定のタイプのみを指定できます。

アプリケーション/ pdf;
画像/ PNG;
アプリケーション/ json;
アプリケーション/ xml;
application / vnd.ms-excel。

Content-TypeおよびAcceptヘッダーは重要であり、重要です。

APIとクライアントは、Content-TypeヘッダーとAcceptヘッダーを渡す必要があります。

APIがJSONで構築されている場合、常にAccept：application / jsonおよびContent-Type application / jsonを渡します。

ファイルタイプの例。

メディアタイプは、インターネット上でのみ、これらのタイプのファイルに似ています。

回答コード

ジュニア開発者の冒険の次の例は、応答コードです。

最も面白い応答率は200 OKです。誰もが彼を愛しています-それはすべてがうまくいったことを意味します。ケースさえありました-200 OKエラーを受け取りました。実際にサーバーに何かが落ち、その応答に応じて、HTMLエラーがコンパイルされたHTMLページが来ます。コード200 OKのアプリケーションjsonをリクエストし、それをどのように使用するかを考えていましたか？あなたは応答で行き、「エラー」という言葉を探し、これは間違いだと思う。

これは機能しますが、HTTPで使用できる他の多くのコードがあり、Roy FieldingはRESTでそれらを使用することをお勧めします。たとえば、エンティティ（記事）の作成に回答できます。

201 Createdは成功したコードです。記事が作成されます。作成された記事を返す必要があります。
202 Acceptedは、リクエストが受け入れられたことを意味しますが、結果は後でなります。これらは長時間実行される操作です。承認されると、ボディは返されません。つまり、応答でContent-Typeを指定しない場合、本文も指定しない場合があります。またはContent-Typeテキスト/プレーン-それだけで、質問はありません。空の文字列は、有効なテキスト/プレーンです。
204コンテンツなし -ボディは完全に存在しない可能性があります。
403禁止 -この記事の作成は許可されていません。
404 Not Found-あなたはどこか間違ったところに登った、例えばそのような方法はない。
409紛争は、ほとんどの人が使用しない極端なケースです。バックエンドではなくクライアントでIDを生成し、その時点で誰かがこの記事を作成できた場合に必要になることがあります。この場合、競合が正解です。

エンティティ作成

次の例：Content-Type：application / jsonなどのエンティティを作成し、このapplication / jsonを渡します。これにより、クライアントがフロントエンドになります。このまさに記事を作成しましょう：

01. POST /articles /1.1 
      

        
        
        
      

     02. Content-Type: application/json 
      

        
        
        
      

     03. { "id": 1, "title": " JSON API"}

コードが応答する場合があります。

422 Unprocessable Entity-未処理のエンティティ。すべてが素晴らしいようです-セマンティクス、コードがあります。
403禁止
500内部サーバーエラー。

しかし、正確に何が起こったのかは絶対に理解できません。どのような種類のエンティティが処理されないのか、なぜそこに行かないのか、そして最終的にサーバーに何が起こったのか？

エラーを返す

応答して、エラーを返すようにしてください（そして、後輩はこれについて知りません）。これは意味論的で正しいです。ちなみに、Fieldingはこれについて書いていません。つまり、後で発明され、RESTの上に構築されました。

バックエンドは、応答でエラーを含む配列を返す場合がありますが、いくつかある場合があります。

01. HTTP/1.1 422 Unprocessable Entity 
      

        
        
        
      

     02. Content-Type: application/json 
      

        
        
        
      

     03. 
      

        
        
        
      

     04. { "errors": [{ 
      

        
        
        
      

     05.   "status": "422", 
      

        
        
        
      

     06. "title": "Title already exist", 
      

        
        
        
      

     07. }]}

各エラーには、独自のステータスとタイトルを付けることができます。これは素晴らしいことですが、RESTに加えて既にコンベンションレベルで行われています。これは、議論をやめ、すぐに適切で適切なAPIを作成するための自転車脱落防止ツールになる可能性があります。

ページネーションを追加

次の例：デザイナーは最初のバックエンド開発者のところに来て、こう言います。これを描きました。」

もっと詳しく考えてみましょう。まず、336ページが印象的です。これを見たとき、私はこの数字を得る方法を考えました。記事のリストをリクエストすると、記事のリストが取得されるため、336を取得する場所。たとえば、1万があります。つまり、すべての記事をダウンロードし、ページ数で割ってこの数を調べる必要があります。非常に長い間、これらの記事を読み込むために、エントリの数をすばやく取得する方法が必要です。ただし、APIがリストを返す場合、記事の配列が応答するため、この数のレコードをどこに配置するかを指定します。エントリの数はどこにも入れられていないため、各記事に追加する必要があるため、各記事に次のように記載されていることがわかります。

ただし、この問題を解決するREST APIの上に規則があります。

リストリクエスト

APIを拡張可能にするために、ページネーションにGETパラメータをすぐに使用できます。現在のページのサイズとその番号。これにより、リクエストしたページの一部が正確に返されます。これは便利です。応答として、すぐに配列を指定することはできませんが、ネストを追加できます。たとえば、データキーには配列、要求したデータが含まれ、メタキーには以前は存在しなかったが、合計が含まれます。

01. GET /articles? page[size]=30&page[number]=2 
      

        
        
        
      

     02. Content-Type: application/json

01. HTTP/1.1 200 OK 
      

        
        
        
      

     02. { 
      

        
        
        
      

     03.   "data": [{ "id": 1, "title": "JSONAPI"}, ...], 
      

        
        
        
      

     04.   "meta": { "count": 10080 } 
      

        
        
        
      

     05. }

このようにして、APIは追加情報を返すことができます。カウントに加えて、他の情報もあるかもしれません-それは拡張可能です。今、後輩がすぐにそれをしなかった場合、そして彼が pajinizationをするように頼まれた後にだけ、彼は互換性のない変更を戻し 、APIを壊し、すべてのクライアントはそれをやり直さなければなりませんでした-通常それは多くのことを痛めます

パジニゼーションは異なります。私はあなたが使うことができるいくつかのライフハックを提供します。

[オフセット] ... [制限]

01. GET /articles? page[offset]=30&page[limit]=30 
      

        
        
        
      

     02. Content-Type: application/json

01. HTTP/1.1 200 OK 
      

        
        
        
      

     02. { 
      

        
        
        
      

     03.   "data": [{ "id": 1, "title": "JSONAPI"}, ...], 
      

        
        
        
      

     04.   "meta": { "count": 10080 } 
      

        
        
        
      

     05. }

データベースを扱う人は、すでに[offset] ... [limit]副皮質を持っているかもしれません。ページ[サイズ] ...ページ[番号]の代わりに使用する方が簡単です。これは少し異なるアプローチです。

カーソル位置

01. GET /articles? page[published_at]=1538332156 
      

        
        
        
      

     02. Content-Type: application/json

01. HTTP/1.1 200 OK 
      

        
        
        
      

     02. { 
      

        
        
        
      

     03.    "data": [{ "id": 1, "title": "JSONAPI"}, ...], 
      

        
        
        
      

     04.    "meta": { "count": 10080 } 
      

        
        
        
      

     05. }

カーソル位置は、レコードのロードを開始するエンティティへのポインターを使用します。たとえば、頻繁に変更されるリストでページネーションまたはロードを使用する場合に非常に便利です。私たちのブログには常に新しい記事が書かれているとしましょう。現在、3番目のページは1分後の3番目のページとは異なりますが、4番目のページに移動すると、リスト全体が移動するため、3番目のページからいくつかのレコードが取得されます。

この問題は、カーソルのページネーションによって解決されます。「その時点で公開された記事の後に来る記事を読み込みます」-純粋に技術的にはもはやシフトすることはできず、それはクールです。

問題N +1

私たちのジュニア開発者が間違いなく遭遇する次の問題は、N + 1の問題です（バックエンダーは理解します）。 10個の記事のリストを表示するとします。記事のリストをアップロードします。各記事には著者がおり、それぞれについて著者をダウンロードする必要があります。発送します：

1件の記事リストのリクエスト。
各記事の著者への10件のリクエスト。

合計：11個のクエリで小さなリストを表示します。

リンクを追加

バックエンドでは、この問題はすべてのORMで解決されています。この接続を忘れずに追加してください。これらの接続は、フロントエンドでも使用できます。これは次のように行われます。

01. GET /articles? include =author 
      

        
        
        
      

     02. Content-Type: application/json

特別なGETパラメータを使用して、バックエンドにあるように、インクルードする名前を付けて、記事とともにロードする必要があるリンクを指定できます。記事をアップロードし、すぐに著者と記事を取得したいとします。答えは次のようになります。

01. /1.1 200  
      

        
        
        
      

     02. { "data": [{ 
      

        
        
        
      

     03.  { attributes: { "id": 1, "title": "JSON API" }, 
      

        
        
        
      

     04.  { relationships: { 
      

        
        
        
      

     05. "author": { "id": 1, "name": "Avdeev" } } 
      

        
        
        
      

     06.  }, ... 
      

        
        
        
      

     07. }]}

独自の記事属性がデータに転送され、主要な関係が追加されました。すべての接続をこのキーに入れます。したがって、1つのリクエストで、以前に11個のリクエストを受信したすべてのデータを受信しました。これは、フロントエンドのN + 1に関する問題を解決するクールなライフハックです。

データ複製の問題

著者を示す10個の記事を表示するとします。すべての記事には1人の著者がいますが、著者のオブジェクトは非常に大きい（たとえば、1メガバイトかかる非常に長い姓）。 1人の著者が回答に10回含まれ、回答に同じ著者を10回含めると10 MBかかります。

すべてのオブジェクトが同じであるため、1人の作成者が10回（10 MB）含まれる問題は、データベースで使用される正規化の助けを借りて解決されます。フロントエンドでは、APIの操作に正規化を使用することもできます-これは非常に便利です。

01. /1.1 200  
      

        
        
        
      

     02. { "data": [{ 
      

        
        
        
      

     03. "id": "1″, "type": "article", 
      

        
        
        
      

     04. "attributes": { "title": "JSON API" }, 
      

        
        
        
      

     05. "relationships": { ... } 
      

        
        
        
      

     06.  "author": { "id": 1, "type": "people" } } 
      

        
        
        
      

     07. }, ... ] 
      

        
        
        
      

     08. }

すべてのエンティティを何らかのタイプでマークします（これは表現タイプ、リソースタイプです）。ロイ・フィールディングは、リソースの概念を導入しました。つまり、彼らは記事を要求し、「記事」を受け取りました。リレーションシップでは、人のタイプへのリンクを配置します。つまり、まだ他の場所に人のリソースがあります。また、データ自体と同じレベルにある別の組み込みキーにリソース自体を取り込みます。

01. /1.1 200  
      

        
        
        
      

     02. { 
      

        
        
        
      

     03. "data": [ ... ], 
      

        
        
        
      

     04. "included": [{ 
      

        
        
        
      

     05.  "id": 1, "type": "people", 
      

        
        
        
      

     06.  "attributes": { "name": "Avdeev" } 
      

        
        
        
      

     07. }] 
      

        
        
        
      

     08. }

したがって、単一のインスタンス内のすべての関連エンティティは、含まれる特別なキーに分類されます。リンクのみを保存し、エンティティ自体はインクルードに保存されます。

要求サイズが減少しました。これは、最初のバックエンドが知らないライフハックです。彼は、後でAPIを破る必要があるときにわかります。

すべてのリソースフィールドが必要というわけではありません

次のライフハックは、すべてのリソースフィールドが必要なわけではない場合に適用できます。これは、返される属性をコンマで区切ってリストする特別なGETパラメーターを使用して行われます。たとえば、記事が大きく、コンテンツフィールドにメガバイトがある場合があり、ヘッダーのリストのみを表示する必要があります-応答にコンテンツは必要ありません。

GET /articles ?fields[article]=title /1.1

01. /1.1 200 OK 
      

        
        
        
      

     02. { "data": [{ 
      

        
        
        
      

     03.  "id": "1″, "type": "article", 
      

        
        
        
      

     04.  "attributes": { "title": " JSON API" }, 
      

        
        
        
      

     05.  }, ... ] 
      

        
        
        
      

     06. }

たとえば、発行日も必要な場合は、カンマ区切りの「発行日」を記述できます。それに応じて、属性には2つのフィールドがあります。これは自転車脱落防止ツールとして使用できる規則です。

記事で検索

多くの場合、検索とフィルターが必要です。これには慣習があります-GETパラメーターの特別なフィルター：

● GET /articles ?filters[search]=api HTTP/1.1

検索。

● GET /articles ?fiIters[from_date]=1538332156 HTTP/1.1

特定の日付から記事をダウンロードします。

● GET /articles ?filters[is_published]=true HTTP/1.1

公開されたばかりの記事をダウンロードします。

● GET /articles ?fiIters[author]=1 HTTP/1.1

第一著者と記事をダウンロードします。

記事の並べ替え

● GET /articles ?sort=title /1.1

タイトル別。

● GET /articles ?sort=published_at HTTP/1.1

発行日別。

● GET /articles ?sort=-published_at HTTP/1.1

公開日で逆方向に。

● GET /articles ?sort=author,-publisbed_at HTTP/1.1

記事が同じ著者のものである場合は、最初に著者、次に逆方向の発行日によって。

URLを変更する必要があります

解決策：既に述べたハイパーメディアは、次のように実行できます。オブジェクト（リソース）を自己記述的にしたい場合、クライアントはハイパーメディアを通じてそれで何ができるかを理解でき、サーバーはクライアントとは独立して開発できます。その後、特別なリンクキーを使用して記事のリストへのリンクを追加できます：

01. GET /articles /1.1 
      

        
        
        
      

     02. { 
      

        
        
        
      

     03. "data": [{ 
      

        
        
        
      

     04.  ... 
      

        
        
        
      

     05. "links": { "self": "http://localhost/articles/1"
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     }, 
      

        
        
        
      

     06.  "relationships": { ... } 
      

        
        
        
      

     07. }], 
      

        
        
        
      

     08. "links": { "self": " http://localhost/articles
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     " } 
      

        
        
        
      

     09. }

または、この記事にコメントをアップロードする方法をクライアントに伝えたい場合：

01. ... 
      

        
        
        
      

     02. "relationships": { 
      

        
        
        
      

     03. "comments": { 
      

        
        
        
      

     04.  "links": { 
      

        
        
        
      

     05. "self": "http://localhost/articles/l/relationships/comments
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     ", 
      

        
        
        
      

     06. "related": " http://localhost/articles/l/comments
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     " 
      

        
        
        
      

     07.  } 
      

        
        
        
      

     08. } 
      

        
        
        
      

     09. }

クライアントはリンクがあることを確認し、リンクをたどってコメントを読み込みます。リンクがない場合、コメントはありません。これは便利ですが、ほとんどありません。フィールディングはRESTの原則を思いつきましたが、それらすべてが私たちの業界に入ったわけではありません。主に2つまたは3つ使用します。

2013年、私がお伝えしたすべてのライフハック、Steve KlabnikはJSON API仕様に統合され、JSONの新しいメディアタイプとして登録されました。そこで、徐々に進化するジュニアバックエンド開発者は、JSON APIを使用しました。

JSON API

Webサイトhttp://jsonapi.org/implementations/ですべての詳細が説明されています。32のプログラミング言語の仕様の170の異なる実装のリストもあります。これらはカタログにのみ追加されます。ライブラリ、パーサー、シリアライザーなどはすでに作成されています。

この仕様はオープンソースなので、誰もがそれに投資しています。私自身、何かを書きました。そういう人は多いと思います。このプロジェクトに自分で参加できます。

JSON APIの長所

JSON API仕様は多くの問題を解決します- すべての人に共通の合意です 。一般的な合意があるため、チーム内で議論することはありません 。自転車小屋は文書化されています。自転車の小屋の材料と塗装方法について合意しています。

開発者が何か間違ったことをして、それを見たとき、私は議論を始めませんが、「JSON APIに準拠していません！」と言って、仕様にそれを示します。彼らは会社で私を嫌っていますが、徐々にそれに慣れて、誰もがJSON APIを好きになり始めました。この仕様に従って新しいデフォルトサービスを作成します。日付キーがあり、メタを追加し、キーを含める準備ができています。フィルター用に予約済みのGETパラメーターフィルターがあります。フィルターと呼ぶものについては議論しません-この仕様を使用します。 URLの作成方法について説明します。

私たちは論争するのではなく、ビジネスタスクを行うので、 開発の生産性は高くなります。仕様を説明し、開発者がバックエンドを読み、APIを作成し、それをねじ込みました-顧客は満足しています。

たとえば、ページネーションなどの一般的な問題はすでに解決されています 。仕様には多くのヒントがあります。

これはJSON（この形式についてはDouglas Crockfordのおかげです）であるため、XMLよりも簡潔で、非常に読みやすく、理解しやすいです。

これがオープンソースであるという事実はプラスとマイナスの両方になり得ますが、私はオープンソースが大好きです。

短所JSON API

オブジェクトは成長しました（日付、属性、含まれるなど）- フロントエンドは回答を解析する必要があります。配列を反復処理し、オブジェクトを歩き回り、reduceがどのように機能するかを知ることができます。すべての初心者開発者がこれらの複雑なことを知っているわけではありません。シリアライザー/デシリアライザーのライブラリがあり、それらを使用できます。一般に、これはデータを操作するだけですが、オブジェクトは大きくなります。

そして、 バックエンドには痛みがあります：

入れ子の制御-インクルードは非常に遠くまで登ることができます。
データベースクエリの複雑さ-それらは時々自動的に構築され、非常に難しいことが判明しました。
セキュリティ-何らかの種類のライブラリを接続する場合は特に、ジャングルに登ることができます。
仕様は読みにくいです。彼女は英語で、それは恐ろしいものでしたが、だんだん誰もがそれに慣れました。
すべてのライブラリが仕様を適切に実装しているわけではありません-これはオープンソースの問題です。

JSON APIの落とし穴

ちょっとハードコア。

問題の関係の数は制限されていません。 インクルード、記事のリクエスト、コメントの追加を行うと、それに応じてこの記事のすべてのコメントを受け取ります。 10,000件のコメントがあります-10,000件のコメントをすべて取得します。

GET /articles/1?include=comments /1.1

01. ... 
      

        
        
        
      

     02. "relationships": { 
      

        
        
        
      

     03. "comments": { 
      

        
        
        
      

     04.  "data": [0 ... ∞] 
      

        
        
        
      

     05. } 
      

        
        
        
      

     06. }

したがって、実際には5 MBがリクエストに応じて来ました。「仕様に書かれています。リクエストを正しく再構成する必要があります。

GET /comments? filters[article]=1& page[size]=30 HTTP/1.1

01. { 
      

        
        
        
      

     02. "data": [0 ... 29] 
      

        
        
        
      

     03. }

記事ごとのフィルターを使用してコメントを要求し、「30個、お願いします」と言って、30個のコメントを取得します。これはあいまいです。

同じことが曖昧に定式化できます ：

● GET /articles/1 ?include=comments HTTP/1.1

コメント付きの記事をリクエストします。

● GET /articles/1/comments HTTP/1.1

記事に関するコメントをリクエストします。

● GET /comments ?filters[article]=1 HTTP/1.1

コメントをリクエストします。

これはまったく同じものです-異なる方法で取得された同じデータには、いくつかのあいまいさがあります。この落とし穴はすぐには見えません。

1対多のポリモーフィック接続は、非常に迅速にRESTに侵入します。

01. GET /comments?include=commentable /1.1 
      

        
        
        
      

     02. 
      

        
        
        
      

     03. ... 
      

        
        
        
      

     04. "relationships": { 
      

        
        
        
      

     05. "commentable" : { 
      

        
        
        
      

     06.  "data": { "type": "article", "id": "1″ } 
      

        
        
        
      

     07. } 
      

        
        
        
      

     08. }

バックエンドにはコメント可能なポリモーフィック接続があります-RESTにクロールします。それが起こるはずですが、それは偽装することができます。 JSON APIでマスクすることはできません。公開されます。

高度なオプションを備えた複雑な多対多の関係 。また、すべてのリンクテーブルが表示されます。

01. GET /users?include =users_comments /1.1 
      

        
        
        
      

     02. 
      

        
        
        
      

     03. ... 
      

        
        
        
      

     04. "relationships": { 
      

        
        
        
      

     05. "users_comments": { 
      

        
        
        
      

     06.  "data": [{ "type": "users_comments", "id": "1″ }, ...] 
      

        
        
        
      

     07. }, 
      

        
        
        
      

     08. }

Swagger

Swaggerは、オンラインドキュメント作成ツールです。

私たちのバックエンド開発者が彼のAPIのドキュメントを書くように頼まれ、彼がそれを書いたとしましょう。 APIが単純な場合、これは簡単です。 JSON APIの場合、Swaggerはそれほど簡単に作成できません。

例： Swaggerペットストア。各メソッドを開くことができます。応答と例を参照してください。

これはペットモデルの例です。ここにクールなインターフェイスがあり、すべてが読みやすいです。

そして、これはJSON APIモデルの作成がどのように見えるかです：

これはそれほど素晴らしいことではありません。データが必要です。関係のあるデータには、5種類のモデルが含まれます。 Swaggerを作成できます。OpenAPIは強力ですが、複雑です。

代替案

OData仕様があり、それは少し後-2015年に登場しました。公式ウェブサイトが保証するように、これは「RESTへの最良の方法」です。次のようになります。

01. GET http://services.odata.org/v4/TripRW/People HTTP/1.1

-GETリクエスト。

02. OData-Version: 4.0

付きの特別なヘッダー。

03. OData-MaxVersion: 4.0

番目の特別バージョンヘッダー

答えは次のようになります。

01. HTTP/1.1 200 OK 
      

        
        
        
      

     02. Content-Type: application/json; odata.metadata=minimal 
      

        
        
        
      

     03. OData-Version: 4.0 
      

        
        
        
      

     04. { 
      

        
        
        
      

     05. '@odata.context': 'http://services.odata.org/V4/ 
      

        
        
        
      

     06. '@odata.nextLink' : 'http://services.odata.org/V4/ 
      

        
        
        
      

     07. 'value': [{ 
      

        
        
        
      

     08.  '@odata.etag': 1W/108D1D5BD423E51581′, 
      

        
        
        
      

     09.  'UserName': 'russellwhyte', 
      

        
        
        
      

     10.  ...

これが拡張アプリケーション/ jsonとオブジェクトです。

最初に、ODataはJSON APIと同じであるため使用しませんでしたが、ODataは簡潔ではありません。巨大なオブジェクトがあり、私にはすべてがはるかに悪い読んでいるようです。 ODataもオープンソースで登場しましたが、より複雑です。

GraphQLはどうですか？

当然、新しいAPI形式を探していたときに、この誇大広告に遭遇しました。

● 高いエントリのしきい値。

フロントエンドの観点から見ると、すべてがクールに見えますが、最初に勉強する必要があるため、新しい開発者にGraphQLを書かせることはできません。これはSQLのようなものです。SQLをすぐに書くことはできません。少なくとも、SQLの内容を読んで、チュートリアルを実行する必要があります。つまり、エントリのしきい値が高くなります。

● ビッグバンの効果。

プロジェクトにAPIがなく、GraphQLの使用を開始した場合、1か月後にそれが私たちに合わないことがわかったため、手遅れになります。松葉杖を書く必要があります。 JSON APIまたはODataで進化できます-最も単純なRESTfulで、徐々に改善され、JSON APIに変わります。

● バックエンドの地獄。

GraphQLはクエリを完全に制御できるため、完全に実装されたJSON APIと同様に、バックエンドで1対1で地獄を呼び出します。これはライブラリであり、多くの質問を解決する必要があります。

ネスト制御;
再帰
周波数制限;
アクセス制御。

結論の代わりに

自転車小屋について議論するのをやめて、自転車脱落防止ツールを仕様として採用し、適切な仕様のAPIを作成することをお勧めします。

自転車小屋の問題を解決するための基準を見つけるには、次のリンクをご覧ください。

● http://jsonapi.org

● http://www.odata.org

● https://graphgl.org

● http://xmlrpc.scripting.com

● https://www.jsonrpc.org

: alexey-avdeev.com github .

, Frontend Conf , 27 28 ++ . , .

? ? ? , ? !

, , , , .

JSON API-仕様に従って動作します

自転車小屋に対処する方法は？ (adsbygoogle = window.adsbygoogle || []).push({});

自転車脱落防止ツール (adsbygoogle = window.adsbygoogle || []).push({});

RESTアーキテクチャーの要件 (adsbygoogle = window.adsbygoogle || []).push({});

RESTfulブログ (adsbygoogle = window.adsbygoogle || []).push({});

記事を削除する (adsbygoogle = window.adsbygoogle || []).push({});

MIMEタイプ (adsbygoogle = window.adsbygoogle || []).push({});

回答コード (adsbygoogle = window.adsbygoogle || []).push({});

エンティティ作成 (adsbygoogle = window.adsbygoogle || []).push({});

エラーを返す (adsbygoogle = window.adsbygoogle || []).push({});

ページネーションを追加 (adsbygoogle = window.adsbygoogle || []).push({});

リストリクエスト (adsbygoogle = window.adsbygoogle || []).push({});

[オフセット] ... [制限] (adsbygoogle = window.adsbygoogle || []).push({});

カーソル位置 (adsbygoogle = window.adsbygoogle || []).push({});

問題N +1 (adsbygoogle = window.adsbygoogle || []).push({});

リンクを追加 (adsbygoogle = window.adsbygoogle || []).push({});

データ複製の問題 (adsbygoogle = window.adsbygoogle || []).push({});

すべてのリソースフィールドが必要というわけではありません (adsbygoogle = window.adsbygoogle || []).push({});

記事で検索 (adsbygoogle = window.adsbygoogle || []).push({});

記事の並べ替え (adsbygoogle = window.adsbygoogle || []).push({});

URLを変更する必要があります (adsbygoogle = window.adsbygoogle || []).push({});

JSON API (adsbygoogle = window.adsbygoogle || []).push({});

JSON APIの長所 (adsbygoogle = window.adsbygoogle || []).push({});

短所JSON API (adsbygoogle = window.adsbygoogle || []).push({});

JSON APIの落とし穴 (adsbygoogle = window.adsbygoogle || []).push({});

Swagger (adsbygoogle = window.adsbygoogle || []).push({});

代替案 (adsbygoogle = window.adsbygoogle || []).push({});

GraphQLはどうですか？ (adsbygoogle = window.adsbygoogle || []).push({});

結論の代わりに (adsbygoogle = window.adsbygoogle || []).push({});

More articles: