JSON bei der Arbeit

Kapitel 1. JSON Überblick

Diese Arbeit wurde mithilfe von KI übersetzt. Wir freuen uns über dein Feedback und deine Kommentare: [e-mail]

Das Datenformat JavaScript Object Notation (JSON) ermöglicht es Anwendungen, über ein Netzwerk zu kommunizieren, in der Regel über RESTful APIs. JSON ist technologieunabhängig, nicht proprietär und portabel. Alle modernen Sprachen (z. B. Java, JavaScript, Ruby, C#, PHP, Python und Groovy) und Plattformen bieten hervorragende Unterstützung für die Erzeugung (Serialisierung) und den Verbrauch (Deserialisierung) von JSON-Daten. JSON ist einfach: Es besteht aus entwicklerfreundlichen Konstrukten wie Objekten, Arrays und Name/Wert-Paaren. JSON ist nicht auf Representational State Transfer (REST) beschränkt, sondern funktioniert auch mit den folgenden Methoden:

• Node.js (speichert Projekt-Metadaten in package.json)

• NoSQL-Datenbanken wie MongoDB (siehe Kapitel 9)

• Messaging-Plattformen wie Kafka (siehe Kapitel 10)

JSON ist ein Standard

Anfangs wurde RESTful Web Services von seinen Gegnern als Nicht-Standard verspottet, aber (genau wie HTTP) ist JSON tatsächlich ein Standard. Sowohl die Internet Engineering Task Force (IETF) als auch die Ecma International (ehemals European Computer Manufacturers Association, kurz ECMA) haben JSON als Standard anerkannt. Douglas Crockford hat JSON ursprünglich im Jahr 2001 entwickelt und es 2006 unter RFC 4627 durch die IETF standardisiert; siehe die JSON-Spezifikation. Im Herbst 2013 hat Ecma International JSON unter ECMA 404 ebenfalls standardisiert; siehe ihre JSON-Spezifikation.Mit der Anerkennung durch Ecma (laut Douglas Crockford; siehe seine Google+ Seite) gilt JSON nun als offizieller internationaler Datenverarbeitungsstandard.

Im März 2014 veröffentlichte Tim Bray eine aktualisierte Version des ursprünglichen Standards von Douglas Crockford als IETF RFC 7158 und RFC 7159, um Fehler im ursprünglichen IETF 4627-Standard zu korrigieren (und ihn damit veraltet zu machen).

Eine kurze Kostprobe

Bevor wir weitermachen, wollen wir uns ein kleines JSON-Beispiel ansehen. Beispiel 1-1 zeigt ein einfaches JSON-Dokument.

Beispiel 1-1. firstValidObject.json

{ "thisIs": "My first JSON document" }

Ein gültiges JSON-Dokument kann entweder der folgenden sein:

• Ein Objekt, das von geschweiften Klammern, { und }

• Ein Array, das von Klammern, [ und ]

Das vorangegangene Beispiel zeigt ein Objekt, das ein einziges Schlüssel/Wert-Paar enthält, wobei der Schlüssel"thisIs" den Wert "My first JSON document" hat.

Damit wir ehrlich sind, sollten wir dieses Dokument mit JSONLint validieren. Füge den Text einfach in den Textbereich ein, klicke auf die Schaltfläche Validieren und du solltest die Seite in Abbildung 1-1 sehen.

Abbildung 1-1. Einfaches/gültiges JSON-Dokument in JSONLint

Beispiel 1-2 zeigt ein einfaches JSON-Array.

Beispiel 1-2. firstValidArray.json

[
  "also",
  "a",
  "valid",
  "JSON",
  "doc"
]

In JSONLint fügst du das JSON-Array in den Textbereich ein und klickst auf die Schaltfläche Validieren. Dann solltest du das in Abbildung 1-2 gezeigte Ergebnis erhalten.

Abbildung 1-2. Gültiges Array in JSONLint

Aber damit greifen wir uns selbst vor. Wir werden die JSON-Syntax in "Core JSON" noch genauer behandeln .

Warum JSON?

Obwohl die Standardisierung durch Ecma International und die IETF dazu beigetragen hat, dass JSON in der IndustrieAkzeptanz gefunden hat, haben auch andere Faktoren JSON populär gemacht:

• Das explosionsartige Wachstum von RESTful APIs auf Basis von JSON

• Die Einfachheit der grundlegenden Datenstrukturen von JSON

• Die zunehmende Beliebtheit von JavaScript

Das Wiederaufleben von JavaScript steigert die Popularität von JSON. In den letzten Jahren hat sich JavaScript zu einer erstklassigen Entwicklungssprache und -umgebung entwickelt. Zu diesem Ökosystem gehören Plattformen wie Node.js und Mode/View/Controller (MVC)-Frameworks wie AngularJS, React, Backbone und Ember. Auch die Zahl der Bücher und Websites, die bewährte Methoden in JavaScript Objects and Patterns vorstellen, ist enorm gestiegen. Laut Douglas Crockford ist JSON eine Untermenge der JavaScript Object Literal Notation und fügt sich nahtlos in die JavaScript-Entwicklung ein.

Tausende von RESTful-APIs nutzen JSON. Eine Beispielliste beliebter JSON-basierter RESTful-APIs umfasst die folgenden:

• LinkedIn

• Twitter

• Facebook

• Salesforce

• GitHub

• DropBox

• Tumblr

• Amazon Web Services (AWS)

Um die Tausenden von verfügbaren JSON-basierten REST-APIs zu sehen, besuche ProgrammableWeb und führe eine Suche nach REST und JSON durch. Nimm dir dann einige Wochen Zeit, um die Ergebnisse durchzusehen.

JSON ist einfach und verdrängt allmählich XML als wichtigstes Datenaustauschformat im Internet. JSON ist leicht zu lesen und seine Strukturen lassen sich leicht in Konzepte übersetzen, die Softwareentwickler gut verstehen - Arrays, Objekte und Name/Wert-Paare. Wir müssen uns nicht mehr den Kopf zerbrechen oder darüber streiten, was ein Element oder ein Attribut sein soll. Objekte und ihre Datenelemente eignen sich viel besser für objektorientiertes (OO) Design und Entwicklung. Ein in JSON formatiertes Dokument ist in der Regel kleiner als sein XML-Pendant, weil JSON weniger Overhead hat und kompakter ist. Das liegt daran, dass es keine Anfangs- und End-Tags gibt, die jedes Datenelement umgeben. Auf Unternehmensebene ist JSON also effizienter zu verarbeiten als XML, weil JSON-Dokumente über ein Netzwerk übertragen und schneller verarbeitet werden können als ihre XML-Pendants.

Obwohl Douglas Crockford JSON ursprünglich als Format für den Datenaustausch (typischerweise mit REST) vorgesehen hatte, findet JSON jetzt auch in Konfigurationsdateien für weit verbreitete Produkte wie Node.js und Sublime Text Verwendung. Node.js hat eine package.json-Datei, die zur Definition der standardmäßigen npm-Paketstruktur verwendet wird; wir werden dies in Kapitel 2 behandeln. Sublime Text, eine beliebte IDE in der Webentwicklergemeinde, verwendet JSON, um sein Erscheinungsbild und seine Paketmanager zu konfigurieren.

Kern JSON

Das JSON-Kerndatenformat umfasst JSON-Daten- und Wertetypen. Wir werden auch Versionen, Kommentare und Datei-/MIME-Typen behandeln.

JSON Datentypen

JSON hat die folgenden zentralen Datentypen:

Name (oder Schlüssel)/Wertepaar

Besteht aus einem Schlüssel (einem Datenattribut) und einem Wert.

Objekt

Eine ungeordnete Sammlung von Name/Wert-Paaren.

Array

Eine Sammlung von geordneten Werten.

Nachdem wir nun die grundlegenden Definitionen besprochen haben, wollen wir uns die einzelnen Datentypen genauer ansehen.

Name/Wert-Paare

Beispiel 1-3 zeigt einige Beispiele für Name/Wert-Paare.

Beispiel 1-3. nameValue.json

{
  "conference": "OSCON",
  "speechTitle": "JSON at Work",
  "track": "Web APIs"
}

Name/Wert-Paare haben die folgenden Eigenschaften:

• Jeder Name (z. B. "conference")

  • Befindet sich auf der linken Seite des Dickdarms (:)

  • Ist ein String und muss von doppelten Anführungszeichen umgeben sein

• Der Wert (z.B. "OSCON") steht rechts vom Doppelpunkt. Im vorangegangenen Beispiel ist der Wertetyp eine Zeichenkette, aber es gibt noch mehrere andere Wertetypen.

Auf Strings und andere gültige Wertetypen gehen wir in "JSON-Wertetypen" näher ein .

Objekte

Objekte bestehen aus Name/Wert-Paaren. Beispiel 1-4 zeigt ein Beispielobjekt, das eine Adresse darstellt.

Beispiel 1-4. simpleJsonObject.json

{
  "address" : {
    "line1" : "555 Any Street",
    "city" : "Denver",
    "stateOrProvince" : "CO",
    "zipOrPostalCode" : "80202",
    "country" : "USA"
  }
}

Beispiel 1-5 zeigt ein Objekt mit ein verschachteltes Array.

Beispiel 1-5. jsonObjectNestedArray.json

{
  "speaker" : {
    "firstName": "Larson",
    "lastName": "Richard",
    "topics": [ "JSON", "REST", "SOA" ]
  }
}

Beispiel 1-6 zeigt ein Objekt, das ein anderes Objekt enthält.

Beispiel 1-6. jsonObjectNestedObject.json

{
  "speaker" : {
    "firstName": "Larson",
    "lastName": "Richard",
    "topics": [ "JSON", "REST", "SOA" ],
    "address" : {
      "line1" : "555 Any Street",
      "city" : "Denver",
      "stateOrProvince" : "CO",
      "zipOrPostalCode" : "80202",
      "country" : "USA"
    }
  }
}

Die Objekte haben die folgenden Eigenschaften:

• in eine beginnende linke geschweifte Klammer ({) und eine endende rechte geschweifte Klammer (}) eingeschlossen sind

• Besteht aus kommagetrennten, ungeordneten Name/Wert-Paaren

• Kann leer sein, { }

• Kann in anderen Objekten oder Arrays verschachtelt werden

Arrays

Beispiel 1-7 zeigt ein Array (mit verschachtelten Objekten und Arrays), das die Präsentationen der Konferenz beschreibt, einschließlich Titel, Länge und Zusammenfassung.

Beispiel 1-7. jsonArray.json

{
  "presentations": [
    {
      "title": "JSON at Work: Overview and Ecosystem",
      "length": "90 minutes",
      "abstract": [ "JSON is more than just a simple replacement for XML when",
                    "you make an AJAX call."
                  ],
      "track": "Web APIs"
    },
    {
      "title": "RESTful Security at Work",
      "length": "90 minutes",
      "abstract": [ "You’ve been working with RESTful Web Services for a few years",
                     "now, and you’d like to know if your services are secure."
                  ],
      "track": "Web APIs"
    }
  ]
}

Arrays haben die folgenden Eigenschaften:

• werden von einer beginnenden linken Klammer ([) und einer endenden rechten Klammer (]) umschlossen

• Besteht aus kommagetrennten, geordneten Werten (siehe nächster Abschnitt)

• Kann leer sein, [ ]

• Kann in anderen Arrays oder Objekten verschachtelt werden

• Eine Indizierung, die auf 0 beginnt oder 1

JSON-Wert-Typen

JSON-Werttypen sind die Datentypen, die auf der rechten Seite des Doppelpunkts (:) eines Name/Wert-Paares stehen. Zu den JSON Value Types gehören die folgenden:

• object

• array

• string

• number

• boolean

• null

Wir haben uns bereits mit Objekten und Arrays beschäftigt; jetzt wollen wir uns auf die übrigen Wertetypen konzentrieren:string, number, boolean und null.

String

Beispiel 1-8 zeigt gültige JSON-Strings.

Beispiel 1-8. jsonStrings.json

[
  "fred",
  "fred\t",
  "\b",
  "",
  "\t",
  "\u004A"
]

Strings haben die folgenden Eigenschaften:

• Strings bestehen aus null oder mehr Unicode-Zeichen, die in Anführungszeichen ("") eingeschlossen sind. In der folgenden Liste findest du weitere gültige Zeichen.

• Strings, die in einfache Anführungszeichen (') eingeschlossen sind, sind nicht gültig.

Außerdem können JSON-Strings die folgenden Zeichen mit umgekehrtem Schrägstrich enthalten:

\"

Doppeltes Zitat

\\

Backslash

\/

Schrägstrich

\b

Rücktaste

\f

Formularvorschub

\n

Newline

\r

Wagenrücklauf

\t

Registerkarte

\u

Gefolgt von vier Hex-Ziffern

Nummer

Beispiel 1-9 zeigt gültige Nummern in JSON.

Beispiel 1-9. jsonNumbers.json

{
  "age": 29,
  "cost": 299.99,
  "temperature": -10.5,
  "unitCost": 0.2,
  "speedOfLight": 1.23e11,
  "speedOfLight2": 1.23e+11,
  "avogadro": 6.023E23,
  "avogadro2": 6.023E+23,
  "oneHundredth": 10e-3,
  "oneTenth": 10E-2
}

Die Zahlen folgen dem doppelpräzisen Fließkommaformat von JavaScript und haben die folgenden Eigenschaften:

• Die Zahlen sind immer zur Basis 10 (nur die Ziffern 0-9 sind erlaubt) und ohne führende Nullen.

• Zahlen können einen Bruchteil haben, der mit einer Dezimalstelle beginnt (.).

• Zahlen können einen Exponenten von 10 haben, der mit der e oder E Notation mit einem Plus- oder Minuszeichen dargestellt wird, um positive oder negative Potenzierung anzuzeigen.

• Oktal- und Hexadezimalformate werden nicht unterstützt.

• Anders als in JavaScript können Zahlen nicht den Wert NaN(keine Zahl für ungültige Zahlen) oder Infinity haben.

Boolesche

Beispiel 1-10 zeigt einen Booleschen Wert in JSON.

Beispiel 1-10. jsonBoolean.json

{
  "isRegistered": true,
  "emailValidated": false
}

Boolesche Wörter haben die folgenden Eigenschaften:

• Booleans können nur einen Wert von true oder false haben.

• Der Wert true oder false auf der rechten Seite des Doppelpunkts (:) ist nicht von Anführungszeichen umgeben.

null

Obwohl es sich technisch gesehen nicht um einen Werttyp handelt, ist null ein spezieller Wert in JSON. Beispiel 1-11 zeigt einennull Wert für den line2 Schlüssel/die Eigenschaft.

Beispiel 1-11. jsonNull.json

{
  "address": {
    "line1": "555 Any Street",
    "line2": null,
     "city": "Denver",
        "stateOrProvince": "CO",
        "zipOrPostalCode": "80202",
        "country": "USA"
    }
}

null Werte haben die folgenden Eigenschaften:

• Sind nicht von Anführungszeichen umgeben

• Angeben, dass ein Schlüssel/eine Eigenschaft keinen Wert hat

• Als Platzhalter fungieren

JSON-Versionen

Laut Douglas Crockford wird es nie eine andere Version des JSON-Kernstandards geben. Das liegt nicht daran, dass JSON perfekt ist; nichts ist perfekt. Der Zweck einer einzigen JSON-Version ist es, die Fallstricke der Abwärtskompatibilität mit früheren Versionen zu vermeiden. Crockford ist der Meinung, dass ein neues Datenformat JSON ersetzen sollte, wenn in der Entwicklergemeinschaft der Bedarf dafür entsteht.

Aber wie du in den folgenden Kapiteln sehen wirst, gilt diese "Keine-Versionen"-Philosophie nur für das zentrale JSON-Datenformat. In Kapitel 5 zum Beispiel ist die Spezifikation zum Zeitpunkt des Verfassens dieses Artikels auf Version 0.5. Bitte beachte, dass diese JSON-bezogenen Spezifikationen von anderen Mitgliedern der JSON-Community erstellt wurden.

JSON-Kommentare

In einem JSON-Dokument gibt es keine Kommentare. Zeitraum.

Laut seinen Beiträgen in der Yahoo! JSON-Gruppe und auf Google+ ließ Crockford zunächst Kommentare zu, entfernte sie aber schon früh aus folgenden Gründen:

• Er war der Meinung, dass Kommentare nicht nützlich sind.

• JSON-Parser hatten Schwierigkeiten, Kommentare zu unterstützen.

• Die Kommentare wurden missbraucht. Er bemerkte zum Beispiel, dass Kommentare für Parsing-Direktiven verwendet wurden, was die Interoperabilität zerstört hätte.

• Das Entfernen von Kommentaren vereinfachte und ermöglichte die plattformübergreifende JSON-Unterstützung.

JSON-Datei und MIME-Typ

Laut der JSON-Kernspezifikation ist .json der Standard-JSON-Dateityp für die Speicherung von JSON-Daten auf Dateisystemen. Der Medientyp (oder MIME-Typ) von JSON, der von der Internet Assigned Numbers Authority (IANA) vergeben wird, istapplication/json. Du findest ihn auf der IANA Media Types Site. RESTful Web Service Producer und Consumers verwenden eine Technik, die als Content Negotiation bekannt ist (die den JSON-MIME-Typ in HTTP-Headern nutzt), um anzuzeigen, dass sie JSON-Daten austauschen.

JSON-Stilrichtlinien

Bei JSON dreht sich alles um Interoperabilität, und es ist wichtig, JSON-Datenfeeds so bereitzustellen, wie es die Verbraucher erwarten.Google hat einen JSON Style Guide veröffentlicht, um die Wartbarkeit und bewährte Methoden zu unterstützen.

Der Google JSON Style Guide ist umfangreich und hier sind die wichtigsten Dinge für einen API-Designer und Entwickler:

• Namen von Immobilien

• Datum Immobilienwerte

• Enum Werte

Namen von Immobilien

Eigenschaftsnamen (in der Google-Sprache) stehen auf der linken Seite des Doppelpunkts in einem Name/Wert-Paar (und Eigenschaftswerte stehen auf der rechten Seite des Bindestrichs). Für die Formatierung eines JSON-Eigenschaftsnamens gibt es zwei verschiedene Stile:

• lowerCamelCase

• snake_case

Mit lowerCamelCase wird ein Name erstellt, indem ein oder mehrere Wörter so zusammengesetzt werden, dass sie wie ein einziges Wort aussehen, wobei der erste Buchstabe in jedem Wort groß geschrieben wird (außer im ersten Wort). Sowohl die Java- als auch die JavaScript-Gemeinschaft verwenden lowerCamelCase in ihren Codierungsanleitungen. Bei snake_case werden alle Buchstaben klein geschrieben und die Wörter durch einen Unterstrich getrennt (_). Die Ruby on Rails-Community bevorzugt jedoch snake_case.

Google verwendet, wie die meisten RESTful APIs, lowerCamelCase für seine Eigenschaftsnamen, wie in Beispiel 1-12 gezeigt.

Beispiel 1-12. jsonPropertyName.json

{
  "firstName": "John Smith"
}

Datum Immobilienwerte

Du denkst vielleicht, dass Datumsformate nicht so wichtig sind, aber das sind sie. Stell dir vor, du tauschst Datumsinformationen zwischen einem Produzenten und einem Konsumenten aus, die aus verschiedenen Ländern oder Kontinenten stammen. Selbst innerhalb eines Unternehmens werden zwei Entwicklungsgruppen wahrscheinlich unterschiedliche Datumsformate verwenden. Es ist wichtig, die Semantik der Interpretation von Zeitstempeln zu berücksichtigen, damit wir eine einheitliche Datums-/Zeitverarbeitung und Interoperabilität über alle Zeitzonen hinweg haben. Der Google JSON Style Guide bevorzugt, dass Datumsangaben dem RFC 3339 Format folgen, wie in Beispiel 1-13 gezeigt.

Beispiel 1-13. jsonDateFormat.json

{
  "dateRegistered": "2014-03-01T23:46:11-05:00"
}

Das vorangehende Datum hat eine Abweichung von der koordinierten Weltzeit (UTC/GMT-Greenwich Mean Time) von-5 Stunden, was der US Eastern Standard Time entspricht. Beachte, dass RFC 3339 ein Profil von ISO 8601 ist. Der Hauptunterschied besteht vor allem darin, dass die ISO 8601 der Internationalen Standardisierungsorganisation den Ersatz des T (das Datum und Uhrzeit trennt) durch ein Leerzeichen erlaubt, während RFC 3339 dies nicht zulässt.

Werte für Breitengrad/Längengrad

Geografische APIs (z. B. Google Maps) und APIs, die mit einem geografischen Informationssystem (GIS) verbunden sind, verwenden Breiten- und Längengraddaten. Um die Konsistenz zu gewährleisten, empfiehlt der Google JSON Style Guide, dass die Breiten-/Längenangaben dem ISO 6709Standard entsprechen. Laut Google Maps lauten die Koordinaten für das Empire State Building in New York City 40.748747° N, 73.985547° W und würden in JSON wie in Beispiel 1-14 dargestellt werden.

Beispiel 1-14. jsonLatLon.json

{
  "empireStateBuilding": "40.748747-73.985547"
}

Dieses Beispiel folgt dem Format ±DD.DDDD±DDD.DDDD, mit den folgenden Konventionen:

• Der Breitengrad kommt zuerst.

• Nördlich (des Äquators) ist der Breitengrad positiv.

• Östlich (des Nullmeridians) ist der Längengrad positiv.

• Der Breitengrad/Längengrad wird als String dargestellt. Wegen des Minuszeichens kann er nicht als Zahl angegeben werden.

Einkerbung

Der Google JSON Style Guide schweigt sich zu diesem Thema aus, aber hier sind ein paar Faustregeln:

• JSON ist ein Serialisierungsformat, kein Präsentationsformat. Daher ist die Einrückung für einen API-Produzenten oder -Konsumenten bedeutungslos.

• Viele JSON-Formatierer lassen dem Benutzer die Wahl zwischen zwei, drei oder vier Leerzeichen, um ein JSON-Dokument zu verschönern.

• JSON hat seinen Ursprung in JavaScript (als Teil des ECMA 262-Standards), aber leider gibt es in der JavaScript-Gemeinschaft keinen einheitlichen Konsens. Viele Menschen und Kodierrichtlinien bevorzugen zwei Leerzeichen, daher wird diese Konvention in diesem Buch aus Gründen der Konsistenz verwendet. Es ist in Ordnung, wenn du einen anderen Stil bevorzugst, aber sei konsequent.

Unser Beispiel - MyConference

Unsere Beispiele in diesem Buch umfassen konferenzbezogene Daten, darunter die folgenden:

• Referenten

• Sitzungen

Unser technischer Stack

Wir beginnen mit der Erstellung eines einfachen JSON-Datenspeichers für Redner und veröffentlichen ihn in einer Stub RESTful API, indem wir die folgenden Schritte ausführen:

1. JSON-Daten mit dem JSON Editor Online modellieren

2. Generiere JSON-Beispieldaten mit dem JSON Generator

3. Erstellen und Bereitstellen einer Stub-API (für zukünftige Tests)

Unser architektonischer Stil-noBackEnd

Unser Architekturstil basiert auf dem Konzept von noBackend. Mit noBackend muss sich der Entwickler in der Anfangsphase der Anwendungsentwicklung keine Gedanken über das Innenleben von Anwendungsservern oder Datenbanken machen.

In den ersten sieben Kapiteln dieses Buches wird die noBackEnd-Architektur verwendet, um den Fokus auf unsere Anwendung aus der Geschäftsperspektive zu halten (Dienste und Daten zuerst), damit wir nicht nur UI-basierte (z. B. mobile, Tablet- und Web-) Clients, sondern auch APIs und nicht webbasierte Client-Anwendungen unterstützen können. Wir werden JSON-Daten mit einfachen Tools wie json-server bereitstellen, um eine RESTful-API zu emulieren.

Mit diesem Ansatz verfolgen wir einen Interface-First-Ansatz bei der Entwicklung und Erstellung einer API,, die Folgendes bietet:

• Agilere, schnelle und iterative Frontend-Entwicklung durch die Entkopplung vom Backend.

• Schnelleres Feedback zur API selbst. Gib die Daten und die URI schnell heraus, damit sie schnell geprüft werden können.

• Eine sauberere Schnittstelle zwischen der API und ihren Verbrauchern.

• Eine Trennung zwischen der Ressource (z. B. Lautsprecher als JSON-Daten), die von der API bereitgestellt wird, und ihrer (eventuellen) internen Implementierung (z. B. Anwendungsserver, Geschäftslogik und Datenspeicher). Das macht es einfacher, die Implementierung in der Zukunft zu ändern. Wenn du eine echte API mit Node.js/Rails/Java (oder einem anderen Framework) zu früh erstellst und einsetzt, hast du bereits in einem sehr frühen Stadium Designentscheidungen getroffen, die es schwierig machen, sie zu ändern, nachdem du mit API-Konsumenten gearbeitet hast.

Eine Stub-API macht Folgendes:

• Die anfängliche Notwendigkeit, mit Servern und Datenbanken zu arbeiten, entfällt

• Ermöglicht es den API-Produzenten (den Entwicklern, die die API schreiben), sich auf das API-Design, die optimale Präsentation der Daten für die Verbraucher und erste Tests zu konzentrieren.

• Ermöglicht es API-Nutzern (z. B. UI-Entwicklern), frühzeitig mit der API zu arbeiten und dem API-Entwicklungsteam Feedback zu geben

Wenn du die leichtgewichtigen Tools in diesem Buch verwendest, wirst du sehen, dass du einen langen Weg gehen kannst, bevor du Code schreibst und ihn auf einem Server bereitstellst. Natürlich wirst du irgendwann eine API implementieren müssen. Wie das geht, zeigen wir in den Kapiteln2-4, in denen wir JavaScript, Ruby on Rails und Java behandeln.

JSON-Daten mit JSON Editor Online modellieren

Die Erstellung eines gültigen JSON-Dokuments von beliebiger Größe und Komplexität ist mühsam und fehleranfällig. JSON Editor Online ist ein großartiges webbasiertes Tool, das Folgendes leistet:

• Ermöglicht es dir, dein JSON-Dokument als Objekte, Arrays und Name/Wert-Paare zu modellieren

• Macht es einfacher, den Text für ein JSON-Dokument schnell und iterativ zu erstellen

JSONmate ist ein weiterer solider Editor im Web, den wir in diesem Buch aber nicht weiter behandeln.

JSON Editor Online Funktionen

Zusätzlich zur JSON-Modellierung und Texterstellung bietet JSON Editor Online die folgenden Funktionen:

JSON-Validierung

Die Validierung erfolgt, während du JSON-Daten in den JSON-Textbereich auf der linken Seite eingibst. Wenn du ein abschließendes Anführungszeichen für einen Wert vergisst (z. B. "firstName": "Ester,), wird neben der folgenden Zeile des JSON-Textes ein X angezeigt, zusammen mit einem Hover-Text, der den Validierungsfehler erklärt.

JSON pretty-printing

Klicke auf die Schaltfläche Einrücken in der oberen linken Ecke des JSON-Textbereichs.

Vollständiges Roundtrip-Engineering zwischen dem Modell und dem JSON-Text

Nachdem du einige Objekte und Schlüssel/Wert-Paare (mit der Schaltfläche Anhängen (+)) im JSON-Modell auf der rechten Seite erstellt hast, generiere JSON-Text, indem du auf die Schaltfläche mit dem linken Pfeil (in der oberen Mitte der Seite) klickst. Du solltest die Änderungen im JSON-Textbereich auf der linken Seite sehen.

Ändere einige Daten im JSON-Textbereich und klicke auf den Pfeil nach rechts. Du solltest die Änderungen im JSON-Modell auf der rechten Seite der Seite sehen.

JSON-Dokument auf Festplatte speichern

Du kannst ein JSON-Dokument auf deinem lokalen Rechner speichern, indem du im Menü "Speichern" die Option "Auf Festplatte speichern" auswählst.

JSON-Dokument importieren

Du kannst ein JSON-Dokument von deinem Computer importieren, indem du im Menü "Öffnen" die Option "Von Datenträger öffnen" wählst.

Bitte erinnere dich daran, dass JSON Editor Online öffentlich zugänglich ist. Das bedeutet, dass alle Daten, die du in diese App einfügst, für andere sichtbar sind. Verwende dieses Tool also nicht mit sensiblen Informationen (persönliche, geschützte und so weiter).

Sprecherdaten im JSON Editor Online

Wenn du mit der Modellierung der Sprecherdaten fertig bist, klicke auf die Schaltfläche mit dem rechten Pfeil, um ein hübsches (eingerücktes) JSON-Dokument zu erstellen, das das Modell darstellt. Abbildung 1-3 zeigt den JSON Editor Online mit unserem anfänglichen Speakers-Modell.

Abbildung 1-3. Sprecherdatenmodell im JSON Editor Online

Dies ist nur ein grobes Modell, aber diese erste Skizze ist ein guter Ausgangspunkt. Nutze das erste Modell, um JSON-Daten zu visualisieren, frühes Feedback zu erhalten und das Design schnell zu überarbeiten. Mit diesem Ansatz kannst du die JSON-Datenstruktur während des gesamten Entwicklungszyklus verfeinern, ohne viel in die Implementierung und Infrastruktur zu investieren.

Generiere JSON-Beispieldaten mit dem JSON Generator

JSON Editor Online bietet einen guten Einstieg, aber wir wollen schnell viele Testdaten erzeugen. Testdaten können aufgrund der Sensibilität der Daten und der Datenmenge, die für sinnvolle Tests benötigt wird, problematisch sein. Selbst mit JSON Editor Online ist es sehr aufwändig, die gewünschte Menge an Testdaten zu erstellen. Wir brauchen ein weiteres Tool, um die Daten zu erstellen, die wir für unsere erste Version der API benötigen. Und hier kommt der JSON Generator ins Spiel. Mit diesem hervorragenden Tool haben wir unsere Testdatendateispeakers.json erstellt. Die Vorlage, mit der wir die Datei speakers.json erstellt haben, ist aufGitHub verfügbar.In Kapitel 5 wird der JSON Generator ausführlicher beschrieben.

Erstellen und Bereitstellen einer Stub-API

Um die Stub-API zu erstellen, verwenden wir die gerade erstellten Speaker-Daten und stellen sie als RESTful-API bereit. Wir nutzen das Node.js-Modul json-server, um die Datei speakers.json als Web-API bereitzustellen; so können wir schnell Prototypen erstellen. Weitere Informationen findest du auf der json-server GitHub-Seite.

Bevor du weitermachst, richte bitte deine Entwicklungsumgebung ein. In Anhang A findest du die folgenden Schritte:

1. Installiere Node.js. json-server ist ein Node.js-Modul, daher musst du zuerst Node.js installieren. Siehe "Node.js installieren".

2. Installiere json-server. Siehe "npm-Module installieren".

3. Installiere JSONView und Postman. Siehe "JSON-Tools im Browser installieren". JSONView druckt JSON in Chrome und Firefox aus. Postman kann auch als eigenständige GUI-Anwendung auf den meisten gängigen Betriebssystemen ausgeführt werden.

Öffne eine Terminalsitzung und führe json-server auf Port 5000 in deiner Befehlszeile aus:

cd chapter-1

json-server -p 5000 ./speakers.json

Du solltest das Folgende sehen:

Wenn du http://localhost:5000/speakers in deinem Browser aufrufst, solltest du (mit dem JSON-Pretty-Printing von JSONView) alle Sprecher aus unserer Stub-API sehen, wie in Abbildung 1-4 dargestellt.

Abbildung 1-4. Sprecher auf dem json-server, betrachtet vom Browser mit JSONView

Du kannst auch einen einzelnen Sprecher erhalten, indem du die id wie folgt an die URI anfügst: http://localhost:5000/speakers/0.

Das ist ein guter Anfang, aber ein Webbrowser hat nur begrenzte Testfunktionen; er kann nur HTTP GETAnfragen senden. Postman bietet die Möglichkeit, eine RESTful API vollständig zu testen. Er kann HTTP GET, POST, PUT und DELETE Anfragen senden und HTTP-Header setzen.

Verwenden wir Postman, um den ersten Sprecher in der API wie folgt zu löschen:

1. Gib die URL http://localhost:5000/speakers/0 ein.

2. Wähle DELETE als HTTP-Verb.

3. Klicke auf die Schaltfläche Senden.

Du solltest sehen, dass DELETE in Postman ordnungsgemäß mit einem 200 (OK) HTTP-Status ausgeführt wurde, wie in Abbildung 1-5 dargestellt.

Abbildung 1-5. Postman: Ergebnisse des Löschens des ersten Sprechers

Vergewissere dich nun, dass der erste Sprecher wirklich gelöscht wurde, indem duhttp://localhost:5000/speakers/0 in deinem Browser erneut aufrufst. Du solltest jetzt die in Abbildung 1-6 gezeigte leere Antwort sehen.

Abbildung 1-6. Überprüfe die Ergebnisse des Löschens des ersten Sprechers

Du kannst json-server beenden, indem du in der Befehlszeile Strg-C drückst.

Mit der Stub-API können wir sie nun von jedem HTTP-Client (z. B. JavaScript, Ruby oder Java) aus aufrufen, um die Daten aus einer externen Anwendung zu konsumieren. Obwohl die meisten unserer Beispiele in den folgenden Kapiteln ein HTTP GET verwenden, können Sie sicher sein, dass json-server mit allen wichtigen HTTP-Verben umgehen kann (GET,POST, PUT, DELETE). Obwohl er in diesem Buch nicht behandelt wird, ist Mountebankein alternativer Server, der robustere Funktionen für Stubbing und Mocking von APIs und Protokollen bietet.

Der wichtigste Punkt dabei ist, dass ein API-Produzent JSON-basierte Tools verwenden kann, um einen Prototyp einer testbaren RESTful-API zu erstellen, ohne Code schreiben zu müssen. Diese Technik ist leistungsstark, weil sie es dem API-Konsumenten ermöglicht, zu testen, ohne darauf warten zu müssen, dass die API zu 100 Prozent fertig ist. Gleichzeitig kann das API-Entwicklungsteam das Design und den Prototyp iterativ verbessern.

Was haben wir abgedeckt?

Zu Beginn haben wir uns mit den Grundlagen von JSON beschäftigt. Wir haben JSON-Daten mit dem JSON Editor Online modelliert und sie mit einer Stub-API bereitgestellt.

Was kommt als Nächstes?

In den nächsten drei Kapiteln wird gezeigt, wie du JSON mit den folgenden Kernplattformen verwenden kannst:

• JavaScript

• Ruby on Rails

• Java

In Kapitel 2 lernst du, wie du JSON in JavaScript mit der Stub-API verwenden kannst, die wir gerade mit json-server erstellt haben.