APIs
REST

REST API

Unsere REST-API bietet eine unkomplizierte M├Âglichkeit, mit der Potter DB zu interagieren, wobei die JSON:API- und OAS-Spezifikation eingehalten wird. In diesem Abschnitt behandeln wir die wichtigsten Aspekte der Verwendung der REST-API, einschlie├člich der verf├╝gbaren Endpunkte und der Formatierung deiner Anfragen und Antworten.

Verf├╝gbare Endpunkte

Um auf Daten aus der REST-API zuzugreifen, musst du eine GET-Anfrage an einen der folgenden Endpunkte schicken:

Aufklappen, um alle Endpunkte zu sehen

B├╝cher

  • /v1/books: Abruf einer Liste von B├╝chern.
  • /v1/books/{id}: Abruf eines einzelnen Buchs anhand seiner ID.
  • /v1/books/{book_id}/chapters: Abruf einer Liste von Kapiteln eines bestimmten Buchs.
  • /v1/books/{book_id}/chapters/{id}: Abruf eines Kapitels eines bestimmten Buchs anhand seiner ID.

Figuren

  • /v1/characters: Abruf einer Liste von Figuren.
  • /v1/characters/{id}: Abruf einer Figur anhand ihrer ID.

Filme

  • /v1/movies: Abruf einer Liste von Filmen.
  • /v1/movies/{id}: Abruf eines Films anhand seiner ID.

Zaubertr├Ąnke

  • /v1/potions: Abruf einer Liste von Zaubertr├Ąnken.
  • /v1/potions/{id}: Abruf eines Zaubertranks anhand seiner ID.

Zauberspr├╝che

  • /v1/spells: Abruf einer Liste von Zauberspr├╝chen.
  • /v1/spells/{id}: Abruf eines Zauberspruchs anhand seiner ID.

IDs m├╝ssen als UUIDs oder Slugs angegeben werden.

OpenAPI Spezifikation (OAS)

Um die Integration zu erleichtern, stellen wir ein OpenAPI Spezifikation (opens in a new tab) Dokument zur Verf├╝gung, das die Endpunkte, Datenmodelle und Anfrage-/Antwortschemata der API beschreibt. Die API entspricht der Version 3.0.3 der OAS-Spezifikation. Unser aktuelles OAS Dokument ist hier (opens in a new tab) zu finden.

JSON:API Format

Unsere REST-API entspricht der JSON:API-Spezifikation (opens in a new tab), die eine einheitliche Methode zur Strukturierung von API-Anfragen und -Antworten bietet. Hier ist ein ├ťberblick ├╝ber die wichtigsten Merkmale von JSON:API im Zusammenhang mit unserer API:

  • Ressourcen: Jede Ressource ist ein Objekt mit einem Typ (type), ID (id) und Attributen (attributes).
  • Relationen: Ressourcen k├Ânnen mit anderen Ressourcen verbunden sein, z. B. ist eine Buch-Ressource mit einer Kapitel-Ressource verbunden und umgekehrt.
  • Paginierung: Wenn eine Antwort eine gro├če Anzahl von Ressourcen enth├Ąlt, wird die Antwort paginiert. Siehe Paginierung f├╝r weitere Infos.
  • Fehler: Fehler werden in standardisiertem Format zur├╝ckgegeben, was die Behandlung und Behebung von Problemen erleichtert.

Abfragen machen

Um eine Abfrage an unsere REST-API zu machen, muss eine GET-Anfrage an einen unserer verf├╝gbaren Endpunkte gestellt werden. Hier ein einfaches Beispiel f├╝r das Abrufen einer Liste von Figuren ├╝ber den Endpunkt /characters:

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

Ausf├╝hrliche Informationen kannst du in der OpenAPI-Spezifikation finden.

Paginierung

Antworten mit einer gro├čen Anzahl von Ressourcen werden paginiert. Die Antwort enth├Ąlt ein links-Objekt mit first-, last-, prev- und next-Links zu den ersten, letzten, vorherigen bzw. n├Ąchsten Seiten der Ergebnisse.

Um die Anzahl der Ressourcen pro Seite zu ├Ąndern, kannst du den Abfrageparameter page[size] verwenden (die maximale Gr├Â├če ist 100):

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

Um die aktuelle Seite zu ├Ąndern, kannst du den Abfrageparameter page[number] verwenden:

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

Ransack

Unsere REST-API unterst├╝tzt erweitertes Filtern und Sortieren mit Ransack (opens in a new tab).

Filtern

Du kannst Ressourcen filtern, indem du einen filter Abfrageparameter zu deiner Anfrage hinzuf├╝gst. Um zum Beispiel Zeichen nach Namen zu filtern, kannst du das Pr├Ądikat name_cont verwenden:

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

Dies wird alle Figuren mit dem Namen "Weasley" zur├╝ckgeben.

Aufklappen, um alle verf├╝gbaren Filter-Pr├Ądikate zu sehen
  • eq: gleich
  • eq_any: gleich jedem
  • eq_all: gleich allen
  • not_eq: nicht gleich
  • not_eq_any: nicht gleich irgendeinem
  • not_eq_all: nicht gleich f├╝r alle
  • matches: entspricht
  • matches_any: passt zu jedem
  • matches_all: passt auf alle
  • does_not_match: stimmt nicht ├╝berein
  • does_not_match_any: stimmt mit keinem ├╝berein
  • does_not_match_all: entspricht nicht allen
  • lt: weniger als
  • lt_any: weniger als jeder
  • lt_all: weniger als alle
  • lteq: kleiner als oder gleich
  • lteq_any: kleiner oder gleich einem
  • lteq_all: kleiner als oder gleich allen
  • gt: gr├Â├čer als
  • gt_any: gr├Â├čer als jeder
  • gt_all: gr├Â├čer als alle
  • gteq: gr├Â├čer als oder gleich
  • gteq_any: gr├Â├čer als oder gleich einem
  • gteq_all: gr├Â├čer als oder gleich allen
  • in: vorhanden
  • in_any: in irgendeinem
  • in_all: in allen
  • not_in: nicht vorhanden
  • not_in_any: nicht in irgendeinem
  • not_in_all: nicht in allen
  • cont: enth├Ąlt
  • cont_any: enth├Ąlt beliebige
  • cont_all: enth├Ąlt alle
  • not_cont: enth├Ąlt nicht
  • not_cont_any: enth├Ąlt keine
  • not_cont_all: enth├Ąlt nicht alle
  • start: beginnt mit
  • start_any: irgendeiner beginnt mit
  • start_all: alle beginnen mit
  • not_start: beginnt nicht mit
  • not_start_any: irgendeiner beginnt nicht mit
  • not_start_all: keiner beginnt mit
  • end: endet mit
  • end_any: irgendeiner endet mit
  • end_all: alle enden mit
  • not_end: endet nicht mit
  • not_end_any: irgendeiner endet nicht mit
  • not_end_all: keiner endet mit
  • 'true': ist wahr
  • 'false': ist falsch
  • present: ist vorhanden
  • blank: ist leer
  • 'null': ist null
  • not_null: ist nicht null

Sortieren

Du kannst Ressourcen sortieren, indem du einen sort Abfrageparameter zu deiner Anfrage hinzuf├╝gst. Um beispielsweise Figuren nach Namen zu sortieren, kannst das Attribut name verwenden (unter Ressourcen findest du alle verf├╝gbaren Attribute):

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

Verwende das Pr├Ąfix -, um in absteigender Reihenfolge zu sortieren.