Einführung in Web-Schnittstellen

Information

• Eine Web-Schnittstelle definiert den Endpunkt, an dem mit PLANTA interagiert werden kann.
  • Web-Schnittstellen können im Modul Web-Schnittstellen angelegt und konfiguriert werden.
• Pro Methode (GET, PUT, POST, DELETE) können eine Implementation und eine Web-Entität hinterlegt werden.
  • Die Implementation gibt vor, wie sich die Schnittstelle verhalten soll, wenn sie aufgerufen wird.
  • Eine Web-Entität
    • beschreibt das Objekt, welches mit den Web-Schnittstellen interagiert (z.B. die Werte, die ein GET-Request zurückgibt).
    • hat eine Bezeichnung und zeigt auf eine Datentabelle.
    • hat n Web-Attribute, die auf jeweils ein Dataitem aus der Datentabelle zeigen.
      • Web-Attribute haben einen Namen und optional eine Transformerklasse, die den jeweiligen Wert transformiert.
    • kann im Modul Web-Entitäten angelegt und konfiguriert werden.

Hinweise

• Um Web-Schnittstellen nutzen zu können, müssen die PLANTA link-Webservices in der web.conf aktiviert und konfiguriert sein:
  • generic_service = true
  • generic_service_interface und generic_service_port enthalten sinnvolle Daten
• Sind die Webservices nicht aktiviert, werden an manchen Stellen die Schaltflächen zur Ausführung verschiedener Aktionen, für die die Webservices erforderlich sind, nicht angezeigt.
• Web-Schnittstellen verwenden standardmäßig den Fully Qualified Domain Name (FQDN) als Adresse. Ist dieser nicht verfügbar, wird auf den Hostnamen der Maschine zurückgegriffen. Ist dieser nicht verfügbar, wird auf die IP der Maschine zurückgegriffen. Ein expliziter Hostname kann mit der Globalen Einstellung planta_link_hostname definiert werden.

Bitte für alle Felder in den Web-Schnittstellen-Modulen Groß-/Kleinschreibung beachten!

Methoden

Verhalten der Klasse DefaultServiceImplementation:

• GET
  • Basierend auf der konfigurierten Web-Entität werden Daten aus der Datenbank abgerufen.
  • Mit einem URL-Filter kann die Auswahl beschränkt werden.
  • Die Response beinhaltet im Body eine JSON-formatierte Liste von Objektrepräsentationen mit den Werten der definierten Attribute der Web-Entität.
• PUT
  • Erwartet im Body des HTTP-Requests ein json-enkodiertes Dictionary, dessen Schlüssel auf die zugeordnete Web-Entität passen.
    • Wenn ein Attribut als Muss-Feld PUT deklariert ist und im Request fehlt, schlägt der Request mit Statuscode 400 fehl.
    • Wenn ein zusätzliches Attribut im Request vorhanden ist, das nicht in der Web-Entität als Attribut vermerkt ist, schlägt der Request ebenfalls mit Statuscode 400 fehl.
  • Wurden die korrekten Attribute angegeben, lädt die Schnittstelle alle Zeilen aus der Datentabelle der Web-Entität, eingeschränkt durch den optionalen URL-Filter.
  • Die entsprechenden Daten werden mit den übergebenen Attributen des Requests aktualisiert.
  • Die Response beinhaltet im Body eine JSON-formatierte Liste von Objektrepräsentationen mit den Werten der definierten Attribute der Web-Entität.
• POST
  • Erwartet im Body des HTTP-Requests ein json-enkodiertes Dictionary, dessen Schlüssel auf die zugeordnete Web-Entität passen.
    • Wenn ein Attribut als Muss-Feld POST deklariert ist und im Request fehlt, schlägt der Request mit Statuscode 400 fehl.
    • Wenn ein zusätzliches Attribut im Request vorhanden ist, das nicht in der Web-Entität als Attribut vermerkt ist, schlägt der Request ebenfalls mit Statuscode 400 fehl.
  • Wurden die korrekten Attribute angegeben, erstellt die Schnittstelle einen neuen Datensatz in der Datentabelle der Web-Entität.
  • Die Autonummer-DIs werden automatisch gefüllt, unabhängig davon, ob sie als Attribute in der Web-Entität angegeben sind.
  • Die übergebenen Werte werden in die entsprechenden Spalten geschrieben.
  • Die Response beinhaltet im Body ein JSON-Objekt mit den Werten der definierten Attribute der Web-Entität.
• DELETE
  • Löscht alle Daten aus der Tabelle der Web-Entität, eingeschränkt durch den optionalen URL-Filter.
  • Im Body der Response ist ein JSON-Objekt enthalten, das wie folgt aufgebaut ist:
    • {'result': {'error': <Liste der nicht gelöschten Objektrepräsentationen mit den Werten der definierten Attribute der Web-Entität>, 'deleted': <Liste der gelöschten Objektrepräsentationen mit den Werten der definierten Attribute der Web-Entität>}}

Fehlerbehandlung

Informationen

• Wenn eine Web-Schnittstelle deaktiviert ist (Aktiv = @N), verhält sich PLANTA project so als als würde der Endpunkt nicht existieren.
• Web-Schnittstellen haben eine generische Funktion zur Fehlerbehandlung, um Fehler, die beim Verarbeiten eines Requests auftreten, einheitlich zu behandeln.
• Im Attribut request_headers sind die Header des Requests als Dictionary abgespeichert.
• Wenn bei einem PUT/POST-Request die Transformation der Attribute fehlgeschlagen ist, gibt es eine Fehlermeldung mit den Feldern die nicht verarbeitet wurden konnten.
• Wenn bei einem PUT/POST-Request Mussfelder fehlen oder überflüssige Felder gesendet werden, gibt es eine Fehlermeldung mit den entsprechenden Feldern.