Blog
Standpunkt

Eine vollständige Einführung in die JSON:API-Spezifikation

Dieser umfassende Leitfaden taucht tief in JSON:API ein: Konzepte, Struktur & leistungsstarke Funktionen.

Leo Schulz

Leo Schulz

5 June 2025

Eine vollständige Einführung in die JSON:API-Spezifikation

REST (Representational State Transfer) bietet einen grundlegenden Architekturstil für das Erstellen von Webdiensten. Er lässt jedoch viele Aspekte der Anfrage- und Antwortformatierung undefiniert. Diese Mehrdeutigkeit kann zu Inkonsistenzen, einem erhöhten Entwicklungsaufwand und einer steileren Lernkurve für API-Nutzer führen. Hier kommt JSON:API ins Spiel, eine Spezifikation, die einen standardisierten, konventionsbasierten Ansatz für das Erstellen von APIs in JSON bietet.

Dieser umfassende Leitfaden bietet einen tiefen Einblick in die JSON:API-Spezifikation und untersucht ihre Kernkonzepte, ihre Struktur und ihre leistungsstarken Funktionen. Wir werden ihre Mechanismen zum Abrufen, Erstellen, Aktualisieren und Löschen von Ressourcen, zum Verwalten von Beziehungen, zum Behandeln von Fehlern und zum Optimieren der Datenübertragung untersuchen und Sie mit dem Wissen ausstatten, um robuste und effiziente APIs zu entwerfen und zu nutzen.

💡
Benötigen Sie ein großartiges API-Testtool, das wunderschöne API-Dokumentation generiert?

Benötigen Sie eine integrierte All-in-One-Plattform für Ihr Entwicklerteam, um mit maximaler Produktivität zusammenzuarbeiten?

Apidog erfüllt alle Ihre Anforderungen und ersetzt Postman zu einem viel günstigeren Preis!
button

Warum JSON:API? Erklärt:

Bevor wir uns mit den technischen Feinheiten befassen, ist es wichtig, die Probleme zu verstehen, die JSON:API lösen soll. Ohne eine gemeinsame Konvention verbringen API-Entwickler oft viel Zeit mit der Diskussion über:

JSON:API geht diese Probleme an, indem es ein klares, konsistentes Format für Anfragen und Antworten definiert. Diese Standardisierung bietet mehrere wesentliche Vorteile:

Kernkonzepte: Die Bausteine eines JSON:API-Dokuments

Im Kern dreht sich JSON:API um das Konzept der Ressourcen. Eine Ressource ist ein einzelner Datensatz eines bestimmten Typs, z. B. ein "Artikel", ein "Benutzer" oder ein "Produkt". Jedes JSON:API-Dokument, ob Anfrage oder Antwort, hält sich an eine bestimmte Struktur.

Die Dokumentstruktur: Elemente der obersten Ebene

Ein JSON:API-Dokument ist ein JSON-Objekt, das mindestens eines der folgenden Elemente der obersten Ebene enthalten muss:

Darüber hinaus kann ein Dokument diese Elemente der obersten Ebene enthalten:

Ressourcenobjekte: Ihre Daten darstellen

Ein Ressourcenobjekt ist der Eckpfeiler von JSON:API und muss Folgendes enthalten:

Ein Ressourcenobjekt kann auch Folgendes enthalten:

Beispiel für ein Ressourcenobjekt:JSON

{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "JSON:API Unveiled",
    "body": "A deep dive into the specification...",
    "created_at": "2025-05-15T10:00:00Z",
    "updated_at": "2025-05-16T14:30:00Z"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "users", "id": "42" }
    },
    "comments": {
      "links": {
        "self": "/articles/1/relationships/comments",
        "related": "/articles/1/comments"
      },
      "data": [
        { "type": "comments", "id": "5" },
        { "type": "comments", "id": "12" }
      ]
    }
  },
  "links": {
    "self": "/articles/1"
  }
}

Ressourcenbezeichnerobjekte

Ressourcenbezeichnerobjekte sind minimale Darstellungen einer Ressource, die nur type und id enthalten. Sie werden innerhalb von Beziehungs-Objekten verwendet, um auf andere Ressourcen zu verlinken, ohne das vollständige Ressourcenobjekt einzubetten.

Beispiel für ein Ressourcenbezeichnerobjekt:JSON

{ "type": "users", "id": "42" }

Links-Objekte stellen URLs für die Navigation in der API bereit. Häufige Link-Elemente umfassen:

Ein Link kann dargestellt werden als:

Beispiel für ein Links-Objekt (innerhalb einer Beziehung):JSON

"links": {
  "self": "http://example.com/articles/1/relationships/author",
  "related": "http://example.com/articles/1/author"
}

Meta-Objekte

Meta-Objekte ermöglichen die Aufnahme von nicht standardmäßigen Meta-Informationen. Dies können beliebige Schlüssel-Wert-Paare sein. Beispielsweise könnte ein meta-Objekt Urheberrechtsinformationen oder Zeitstempel im Zusammenhang mit den Daten enthalten.

Beispiel für ein Meta-Objekt:JSON

"meta": {
  "copyright": "Copyright 2025 Example Corp.",
  "authors": ["John Doe"]
}

Content-Negotiation: Die richtige Sprache sprechen

JSON:API definiert seinen eigenen Medientyp: application/vnd.api+json.

Server können andere Medientypen neben application/vnd.api+json über Standard-Content-Negotiation unterstützen.

Daten abrufen: Ressourcen und Sammlungen abrufen

JSON:API bietet robuste Mechanismen für Clients, um Daten genau nach Bedarf abzurufen.

Einzelne Ressourcen abrufen

Um eine einzelne Ressource abzurufen, sendet ein Client eine GET-Anfrage an einen Endpunkt, der diese Ressource darstellt.

Anfrage:

GET /articles/1

Accept: application/vnd.api+json

Erfolgreiche Antwort (200 OK):JSON

{
  "links": {
    "self": "/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Rocks!"
    }
    // ... other attributes and relationships
  }
}

Wenn die Ressource nicht existiert, sollte der Server 404 Not Found zurückgeben. Wenn ein Link zu einer zugehörigen Eins-zu-Eins-Ressource abgerufen wird und die Beziehung leer ist, sind die primären Daten null.

Sammlungen von Ressourcen abrufen

Um eine Sammlung von Ressourcen abzurufen, sendet ein Client eine GET-Anfrage an einen Endpunkt, der diese Sammlung darstellt.

Anfrage:

GET /articles

Accept: application/vnd.api+json

Erfolgreiche Antwort (200 OK):JSON

{
  "links": {
    "self": "/articles",
    "next": "/articles?page[offset]=10",
    "last": "/articles?page[offset]=50"
  },
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": { "title": "Article 1" }
      // ...
    },
    {
      "type": "articles",
      "id": "2",
      "attributes": { "title": "Article 2" }
      // ...
    }
    // ... more articles
  ]
}

Wenn die Sammlung leer ist, ist das Element data ein leeres Array [].

Beziehungen: Ressourcen verbinden

Beziehungen sind ein grundlegender Bestandteil der meisten Datenmodelle. JSON:API bietet eine klare Möglichkeit, diese zu definieren und mit ihnen zu interagieren.

Beziehungen darstellen

Beziehungen werden innerhalb des relationships-Objekts einer Ressource definiert. Jeder Eintrag im relationships-Objekt stellt eine eindeutige Beziehung dar (z. B. "Autor", "Kommentare").

Ein Beziehungs-Objekt muss mindestens eines der folgenden Elemente enthalten:

Beispiel für "author" (Eins-zu-Eins) und "comments" (Eins-zu-Viele)-Beziehungen:JSON

"relationships": {
  "author": {
    "links": {
      "self": "/articles/1/relationships/author",
      "related": "/articles/1/author"
    },
    "data": { "type": "users", "id": "42" }
  },
  "comments": {
    "links": {
      "self": "/articles/1/relationships/comments",
      "related": "/articles/1/comments"
    },
    "data": [
      { "type": "comments", "id": "5" },
      { "type": "comments", "id": "12" }
    ]
  }
}

Beziehungen abrufen

Clients können mithilfe der bereitgestellten Links Informationen über eine Beziehung selbst oder die zugehörigen Ressourcen abrufen.

Abrufen der Beziehungs-Verknüpfung (Selbst-Link):

GET /articles/1/relationships/comments

Accept: application/vnd.api+json

Dies gibt eine Sammlung von Ressourcenbezeichnerobjekten für die Kommentare zurück, die sich auf den Artikel "1" beziehen.

Abrufen zugehöriger Ressourcen (zugehöriger Link):

GET /articles/1/comments

Accept: application/vnd.api+json

Dies gibt eine Sammlung vollständiger Kommentar-Ressourcenobjekte zurück, die sich auf den Artikel "1" beziehen.

Datenabruf optimieren

JSON:API bietet mehrere Funktionen, um den Datenabruf zu optimieren, die Bandbreite zu minimieren und die Leistung auf Client-Seite zu verbessern.

Zusammengesetzte Dokumente: Reduzierung von HTTP-Anfragen mit include

Um mehrere Roundtrips zum Server zum Abrufen zugehöriger Ressourcen zu vermeiden, können Clients mit JSON:API anfordern, dass zugehörige Ressourcen mithilfe des Abfrageparameters include in die primäre Antwort aufgenommen werden. Der Server lädt diese Ressourcen dann in das included-Array der obersten Ebene nebenbei.

Anfrage zum Abrufen eines Artikels und zum Einbeziehen seines Autors und seiner Kommentare:

GET /articles/1?include=author,comments

Accept: application/vnd.api+json

Antwort (200 OK):JSON

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": { "title": "..." },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "42" }
      },
      "comments": {
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "42",
      "attributes": { "name": "John Doe" }
    },
    {
      "type": "comments",
      "id": "5",
      "attributes": { "body": "Great article!" }
    },
    {
      "type": "comments",
      "id": "12",
      "attributes": { "body": "Very informative." }
    }
  ]
}

Spärliche Feldmengen: Nur erforderliche Felder abrufen

Clients können anfordern, dass nur bestimmte Felder (Attribute und Beziehungen) für Ressourcen eines bestimmten Typs mithilfe des Abfrageparameters fields[TYPE] zurückgegeben werden. Dies reduziert die Payload-Größe.

Anfrage zum Abrufen von Artikeln, aber nur ihres Titels und ihrer Autorbeziehung:

GET /articles?fields[articles]=title,author

Accept: application/vnd.api+json

Antwort (200 OK):JSON

{
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "Article 1"
      },
      "relationships": {
        "author": {
          "data": { "type": "users", "id": "42" }
        }
      }
    }
    // ... other articles with only title and author
  ]
}

Sortieren

Clients können anfordern, dass die primären Daten mithilfe des Abfrageparameters sort sortiert werden.

Anfrage zum Abrufen von Artikeln, sortiert nach Erstellungsdatum (absteigend) und dann nach Titel (aufsteigend):

GET /articles?sort=-created_at,title

Accept: application/vnd.api+json

Paginierung

JSON:API unterstützt verschiedene Paginierungsstrategien. Die Spezifikation definiert, wie Paginierungs-Links (first, prev, next, last) im links-Objekt der obersten Ebene angezeigt werden sollen. Die tatsächliche Paginierungsstrategie (z. B. seitenbasiert, offsetbasiert, cursorbasiert) wird vom Server mithilfe von Abfrageparametern wie page[number], page[size], page[offset], page[limit] oder page[cursor] bestimmt.

Beispiel für seitenbasierte Paginierungs-Links:JSON

"links": {
  "self": "/articles?page[number]=2&page[size]=10",
  "first": "/articles?page[number]=1&page[size]=10",
  "prev": "/articles?page[number]=1&page[size]=10",
  "next": "/articles?page[number]=3&page[size]=10",
  "last": "/articles?page[number]=5&page[size]=10"
}

Clients sollten diese bereitgestellten Links verwenden, anstatt ihre eigenen Paginierungs-URLs zu erstellen.

Filtern

Die Spezifikation reserviert den Abfrageparameter filter für das Filtern von Daten. Sie schreibt jedoch keine bestimmte Filterstrategie vor. Server können jede Strategie implementieren, z. B. filter[attribute]=value oder komplexere ausdrucksbasierte Filterung.

Beispiel (von JSON:API empfohlen, aber nicht vorgeschrieben):

GET /comments?filter[post]=1 (Kommentare für Beitrag mit ID 1 abrufen)

GET /comments?filter[post]=1,2&filter[author]=12 (Kommentare für Beiträge 1 oder 2 vom Autor 12 abrufen)

Clients sollten die Dokumentation der API konsultieren, um ihre spezifischen Filterfunktionen zu verstehen.

Daten ändern: Ressourcen erstellen, aktualisieren und löschen

JSON:API definiert klare Protokolle für Datenmanipulationsvorgänge.

Ressourcen erstellen

Um eine Ressource zu erstellen, sendet ein Client eine POST-Anfrage an eine URL, die eine Sammlung von Ressourcen darstellt. Der Anfragetext muss ein einzelnes Ressourcenobjekt mit type und optional attributes und relationships enthalten. Der Client darf keine id für die neue Ressource bereitstellen (es sei denn, clientgenerierte IDs werden unterstützt und aktiviert).

Anfrage:

POST /articles

Accept: application/vnd.api+json

Content-Type: application/vnd.api+jsonJSON

{
  "data": {
    "type": "articles",
    "attributes": {
      "title": "New Article Title",
      "body": "Content of the new article."
    },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "42" }
      }
    }
  }
}

Erfolgreiche Antworten:

Wenn versucht wird, eine Ressource mit einer clientgenerierten ID zu erstellen, die bereits existiert, und der Server die Aktualisierung über POST nicht unterstützt, muss er 409 Conflict zurückgeben.

Ressourcen aktualisieren

Ressourcen werden mithilfe der PATCH-HTTP-Methode aktualisiert. Die Anfrage muss die id der zu aktualisierenden Ressource enthalten. Der Anfragetext enthält ein Ressourcenobjekt mit type, id und den attributes und/oder relationships, die aktualisiert werden sollen.

Anfrage zum Aktualisieren des Titels eines Artikels und einer seiner Beziehungen:

PATCH /articles/1

Accept: application/vnd.api+json

Content-Type: application/vnd.api+jsonJSON

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Updated Article Title"
    },
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "3" },
          { "type": "tags", "id": "4" }
        ]
      }
    }
  }
}

Wichtige Punkte für Aktualisierungen:

Erfolgreiche Antworten:

Wenn die zu aktualisierende Ressource nicht existiert, muss der Server 404 Not Found zurückgeben.

Beziehungen direkt aktualisieren

JSON:API bietet spezifische Möglichkeiten, Beziehungen zu verwalten, ohne die Attribute der primären Ressource zu beeinflussen.

{
  "data": { "type": "users", "id": "24" } // Assign new author or null to clear
}

{
  "data": [
    { "type": "comments", "id": "101" },
    { "type": "comments", "id": "102" }
  ]
}

Explore more

Fathom-R1-14B: Fortschrittliches KI-Argumentationsmodell aus Indien

Fathom-R1-14B: Fortschrittliches KI-Argumentationsmodell aus Indien

Künstliche Intelligenz wächst rasant. FractalAIResearch/Fathom-R1-14B (14,8 Mrd. Parameter) glänzt in Mathe & Logik.

5 June 2025

Cursor 1.0 mit BugBot: KI-gestütztes Automatisierungstest-Tool ist da:

Cursor 1.0 mit BugBot: KI-gestütztes Automatisierungstest-Tool ist da:

Die Softwareentwicklung erlebt Innovationen durch KI. Cursor, ein KI-Editor, erreicht mit Version 1.0 einen Meilenstein.

5 June 2025

30+ öffentliche Web 3.0 APIs, die Sie jetzt nutzen können

30+ öffentliche Web 3.0 APIs, die Sie jetzt nutzen können

Der Aufstieg von Web 3.0: Dezentral, nutzerorientiert, transparent. APIs ermöglichen innovative dApps und Blockchain-Integration.

4 June 2025

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenDownload