API
REST

REST API

Na┼íe RESTful API pon├║ka priamo─Źiary sp├┤sob interakcie s PotterDB v s├║lade s JSON:API a OAS ┼ípecifik├íciou. V tejto kapitole sa obozn├ímite s k─ż├║─Źov├Żmi aspektmi pou┼ż├şvanie Potter DB REST API, okrem in├ęho sa dozviete viac o jednotliv├Żch koncov├Żch bodov a form├ítovan├ş po┼żiadaviek a odpoved├ş.

Koncov├ę body

Na z├şskanie d├ít cez REST API po┼ílite po┼żiadavku GET jedn├ęmu z nasleduj├║cich koncov├Żch bodov:

Kliknut├şm zobraz├şte v┼íetky koncov├ę body

Knihy (books)

  • /v1/books: Vr├íti zoznam kn├şh.
  • /v1/books/{id}: Vr├íti jednu knihu na z├íklade jej ID.
  • /v1/books/{book_id}/chapters: Vr├íti zoznam kapitol ur─Źitej knihy.
  • /v1/books/{book_id}/chapters/{id}: Vr├íti jednu kapitolu ur─Źitej knihy na z├íklade jej ID.

Postavy (characters)

  • /v1/characters: Vr├íti zoznam post├ív.
  • /v1/characters/{id}: Vr├íti jednu postavu na z├íklade jej ID.

Filmy (movies)

  • /v1/movies: Vr├íti zoznam filmov.
  • /v1/movies/{id}: Vr├íti jeden film na z├íklade jeho ID.

Odvary (potions)

  • /v1/potions: Vr├íti zoznam odvarov.
  • /v1/potions/{id}: Vr├íti jeden odvar na z├íklade jeho ID.

Spells (Zakl├şnadl├í)

  • /v1/spells: Vr├íti zoznam zakl├şnadiel.
  • /v1/spells/{id}: Vr├íti jedno zakl├şnadlo na z├íklade jeho ID.

ID mus├ş by┼ą vo form├íte UUID alebo slug.

┼ápecifik├ícia pod─ża ┼ítandardu OpenAPI (OAS)

Na u─żah─Źenie integr├ície poskytujeme ┼ípecifik├íciu v s├║lade s OpenAPI (opens in a new tab) ┼ítandardom, ktor├í popisuje jednotliv├ę koncov├ę body API, d├ítov├ę modely a sch├ęmy po┼żiadaviek a odpoved├ş. Na┼íe API sa riadi verziou 3.0.3 OpenAPI ┼ítandardu. Aktu├ílnu API ┼ípecifik├íciu n├íjdete tu (opens in a new tab).

Formát JSON:API

Na┼íe REST API sa riadi ┼ípecifik├íciou JSON:API (opens in a new tab), ktor├í zaru─Źuje konzistentn├Ż sp├┤sob ┼ítrukt├║rovania API po┼żiadaviek a odpoved├ş. Tu je preh─żad k─ż├║─Źov├Żch vlastnost├ş ┼ípecifik├ície JSON:API v kontexte n├í┼ího API:

  • Zdrojov├ę objekty: Ka┼żd├Ż zdroj je reprezentovan├Ż ako objekt, ktor├Ż m├í type, id a attributes.
  • Vz┼ąahy: Zdroje m├┤┼żu ma┼ą vz┼ąah k in├Żm zdrojom, napr├şklad zdroj book je vo vz┼ąahu k zdroju chapter a naopak.
  • Str├ínkovanie: Odpovede obsahuj├║ce ve─żk├Ż po─Źet zdrojov s├║ str├ínkovan├ę. Viac inform├íci├ş n├íjdete v ─Źasti Str├ínkovanie.
  • Chyby: Chyby sa vracaj├║ v ┼ítandardizovanom form├íte, ─Źo u─żah─Źuje spracovanie a rie┼íenie probl├ęmov.

Posielanie po┼żiadaviek

Na z├şskanie d├ít cez REST API po┼ílite po┼żiadavku GET jedn├ęmu z koncov├Żch bodov. Tu je jednoduch├Ż pr├şklad ako z├şska┼ą list post├ív z koncov├ęho bodu /characters:

GET https://api.potterdb.com/v1/characters

Podrobn├ę inform├ície n├íjdete v ┼ípecifik├ícii pod─ża ┼ítandardu OpenAPI, ktor├║ n├íjde tu (opens in a new tab).

Stránkovanie

Odpovede obsahuj├║ce ve─żk├Ż po─Źet zdrojov s├║ str├ínkovan├ę. Str├ínkovan├í odpove─Ć obsahuje objekt links s odkazmi first, last, prev a next na prv├║, posledn├║, predch├ídzaj├║cu a nasleduj├║cu str├ínku.

Ak chcete zmeni┼ą po─Źet zdrojov na str├ínke, pou┼żite parameter page[size] (maxim├ílny po─Źet je 100).

GET https://api.potterdb.com/v1/characters?page[size]=25

Ak chcete zmeni┼ą aktu├ílnu str├ínku, pou┼żite parameter page[number]:

GET https://api.potterdb.com/v1/characters?page[number]=2

Ransack

Na┼íe REST API podporuje pokro─Źil├ę filtrovanie a zora─Ćovanie pomocou kni┼żnice Ransack (opens in a new tab).

Filtrovanie

Zdroje m├┤┼żete filtrova┼ą pridan├şm parametru filter do va┼íej po┼żiadavky. Ak chcete napr├şklad filtrova┼ą postavy pod─ża mena, pou┼żite predik├ít name_eq:

GET https://api.potterdb.com/v1/characters?filter[name_cont]=Weasley

T├íto po┼żiadavka vr├íti v┼íetky postavy s menom "Weasley".

Kliknut├şm zobraz├şte v┼íetky dostupn├ę filtre
  • eq: presne sa zhoduje
  • eq_any: presne sa zhoduje s aspo┼ł jedn├Żm
  • eq_all: presne sa zhoduje so v┼íetk├Żmi
  • not_eq: nezhoduje sa presne
  • not_eq_any: nezhoduje sa presne s aspo┼ł jedn├Żm
  • not_eq_all: nezhoduje sa presne so v┼íetk├Żmi
  • matches: zhoduje sa
  • matches_any: zhoduje sa s aspo┼ł jedn├Żm
  • matches_all: zhoduje sa so v┼íetk├Żmi
  • does_not_match: nezhoduje sa
  • does_not_match_any: nezhoduje sa s aspo┼ł jedn├Żm
  • does_not_match_all: nezhoduje sa so v┼íetk├Żmi
  • lt: men┼í├ş ako
  • lt_any: men┼í├ş ako aspo┼ł jeden
  • lt_all: men┼í├ş ako v┼íetky
  • lteq: men┼í├ş alebo rovn├Ż
  • lteq_any: men┼í├ş alebo rovn├Ż aspo┼ł jedn├ęmu
  • lteq_all: men┼í├ş alebo rovn├Ż v┼íetk├Żm
  • gt: v├Ą─Ź┼í├ş ako
  • gt_any: v├Ą─Ź┼í├ş ako aspo┼ł jeden
  • gt_all: v├Ą─Ź┼í├ş ako v┼íetky
  • gteq: v├Ą─Ź┼í├ş alebo rovn├Ż
  • gteq_any: v├Ą─Ź┼í├ş alebo rovn├Ż aspo┼ł jedn├ęmu
  • gteq_all: v├Ą─Ź┼í├ş alebo rovn├Ż v┼íetk├Żm
  • in: v
  • in_any: v aspo┼ł jednom
  • in_all: vo v┼íetk├Żch
  • not_in: nie v
  • not_in_any: nie v aspo┼ł jednom
  • not_in_all: nie v ani jednom
  • cont: obsahuje
  • cont_any: obsahuje aspo┼ł jeden
  • cont_all: obsahuje v┼íetky
  • not_cont: neobsahuje
  • not_cont_any: neobsahuje aspo┼ł jeden
  • not_cont_all: neobsahuje v┼íetky
  • start: za─Ź├şna na
  • start_any: za─Ź├şna na aspo┼ł jeden
  • start_all: za─Ź├şna na v┼íetky
  • not_start: neza─Ź├şna na
  • not_start_any: neza─Ź├şna na aspo┼ł jeden
  • not_start_all: neza─Ź├şna na v┼íetky
  • end: kon─Ź├ş na
  • end_any: kon─Ź├ş na aspo┼ł jeden
  • end_all: kon─Ź├ş na v┼íetky
  • not_end: nekon─Ź├ş na
  • not_end_any: nekon─Ź├ş na aspo┼ł jeden
  • not_end_all: nekon─Ź├ş na v┼íetky
  • 'true': je pravdiv├Ż
  • 'false': je nepravdiv├Ż
  • present: je pr├ştomn├Ż
  • blank: je pr├ízdny
  • 'null': je nulov├Ż
  • not_null: nie je nulov├Ż

Zora─Ćovanie

Zdroje m├┤┼żete zoradi┼ą pridan├şm parametru sort do va┼íej po┼żiadavky. Ak chcete napr├şklad zoradi┼ą postavy pod─ża mena, pou┼żite atrib├║t name (v┼íetky dostupn├ę atrib├║ty n├íjdete v ─Źasti Zdroje):

GET https://api.potterdb.com/v1/characters?sort=name

Ak chcete zoradi┼ą zdroje v zostupnom porad├ş, pou┼żite prefix -.