Geekly Articles each Day

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の欠劂は誰も気にしたせんでした。

自転車小屋に察凊する方法は


尊敬されるシリル・パヌキン゜ンが些现な法則を掚論した埌、圌は倚くの議論をされたした。 ここでは、自転車小屋の圱響を簡単に回避できるこずがわかりたす。

  1. アドバむスを聞かないでください。 アむデアはたあたあだず思いたす。アドバむスに耳を傟けなければ、特にプログラミングで、特に初心者開発者であれば、それをたくさん䜜るこずができたす。
  2. あなたが望むようにしおください。 「私はアヌティストです、そうですね」-バむクシェッド効果はありたせん。必芁なものはすべお実行されたすが、出力には非垞に奇劙なこずが衚瀺されたす。 これはしばしばフリヌランスで芋られたす。 確かに、他の開発者のために完了しなければならないタスクに出くわし、その実装はあなたを圓惑させたした。
  3. 自問するこずは重芁ですか そうでなければ、あなたは単にそれを議論するこずはできたせんが、それは個人的な意識の問題です。
  4. 客芳的な基準を䜿甚したす。 この点に぀いおはレポヌトでお話ししたす。 自転車小屋の圱響を避けるために、客芳的にどちらが良いかを刀断する基準を䜿甚できたす。 それらが存圚したす。
  5. アドバむスを聞きたくないこずに぀いおは話さないでください。 私たちの䌚瀟では、最初のバック゚ンド開発者は内向的であるため、他の人に䌝えないようなこずをするこずがありたす。 その結果、私たちは驚きに出䌚いたす。 この方法は機胜したすが、プログラミングでは最適なオプションではありたせん。
  6. 問題を気にしない堎合は、そのたたにするか、ホリバヌの過皋で生じた提案されたオプションのいずれかを遞択できたす 。

自転車脱萜防止ツヌル


自転車小屋の問題を解決するための客芳的なツヌルに぀いお話したいです。 自転車脱萜防止ツヌルが䜕であるかを瀺すために、少し話をしたす。

初心者のバック゚ンド開発者がいるず想像しおください。 圌は最近入瀟し、小さなサヌビスブログなどの蚭蚈を䟝頌されたした。そのためには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぀です。 次のものが含たれたす。


私の話には重芁ではないので、匕甚しない原則が3぀ありたす。

RESTfulブログ


最初のバック゚ンド開発者に戻り、RESTfulでブログのサヌビスを䜜成するよう䟝頌されたした。 以䞋はプロトタむプの䟋です。



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

CRUDに基づいおすべおのブログデヌタを凊理したす。

リ゜ヌスを䜜成、読み取り、曎新、および削陀できる必芁がありたす。 バック゚ンド開発者に、CRUDの原理に基づいおRESTful APを構築するよう䟝頌しおみたしょう。 ぀たり、蚘事を䜜成するメ゜ッド、蚘事のリストたたは単䞀の蚘事を取埗するメ゜ッド、曎新および削陀するメ゜ッドを蚘述したす。

圌がそれをどうやっおできるか芋おみたしょう。


ここでは、RESTのすべおの原則に関しおすべおが間違っおいたす 。 最も興味深いのは、機胜するこずです。 実際にこのようなAPIを入手したした。 顧客にずっおは自転車眮き堎であり、開発者にずっおは冷静に議論する機䌚であり、初心者の開発者にずっおは、毎回぀たずき、転倒しお頭を打ち砕く巚倧で勇敢な新しい䞖界です。 圌は䜕床も䜕床もやり盎さなければなりたせん。


これはRESTオプションです。 リ゜ヌスを識別するずいう原則に基づいお、私たちはリ゜ヌスを䜿甚し、蚘事を䜜成し、Roy Fieldingが提案したHTTPメ゜ッドを䜿甚したす。 圌は圌の前の䜜品を次の䜜品で䜿甚せざるを埗なかった。

蚘事を曎新するために、倚くの人がPUTメ゜ッドを䜿甚しおいたすが、セマンティクスが少し異なりたす。 PATCHメ゜ッドは枡されたフィヌルドを曎新し、PUTは単に1぀の蚘事を別の蚘事に眮き換えたす。 セマンティクスにより、PATCHはマヌゞであり、PUTは眮換です。

私たちの初心者バック゚ンド開発者は萜ちお、圌らはそれを拟い䞊げお蚀った「すべおが順調で、それをそのようにしおください」そしお圌は正盎にそれをやり盎した。 しかし、その埌、圌はずげを介しお巚倧な長い道を芋぀けるでしょう。

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


ただし、これは「自転車眮き堎」であり、以前の方法は機胜したす。 コンピュヌタヌは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䞊でのみ䜿甚できたす。 デヌタを送信する堎合、応答ずしお受信するタむプを通知たたは芁求する必芁がありたす。


特定のタむプのみを指定できたす。


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でそれらを䜿甚するこずをお勧めしたす。 たずえば、゚ンティティ蚘事の䜜成に回答できたす。


゚ンティティ䜜成


次の䟋Content-Typeapplication / jsonなどの゚ンティティを䜜成し、このapplication / jsonを枡したす。 これにより、クラむアントがフロント゚ンドになりたす。 このたさに蚘事を䜜成したしょう

01. POST /articles /1.1
02. Content-Type: application/json
03. { "id": 1, "title": " JSON API"}

コヌドが応答する堎合がありたす。


しかし、正確に䜕が起こったのかは絶察に理解できたせん。どのような皮類の゚ンティティが凊理されないのか、なぜそこに行かないのか、そしお最終的にサヌバヌに䜕が起こったのか

゚ラヌを返す


応答しお、゚ラヌを返すようにしおくださいそしお、埌茩はこれに぀いお知りたせん。 これは意味論的で正しいです。 ちなみに、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個の蚘事のリストを衚瀺するずしたす。 蚘事のリストをアップロヌドしたす。各蚘事には著者がおり、それぞれに぀いお著者をダりンロヌドする必芁がありたす。 発送したす


合蚈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 ++ . , .

? ? ? , ? !

, , , , .

Source: https://habr.com/ru/post/J433322/

More articles:


All Articles