API-Endpunkt für eine Applikation erstellen - Advanced

Inhalt dieses Tutorials

Dieses Tutorial beschreibt zwei etwas weiter fortgeschrittenere Anwendungsfälle für das Erstellen von API-Endpunkten. Dabei geht es darum, die bei einem Request zurückgegebenen Werte einzuschränken bzw. zu filtern.

Im ersten Anwendungsfall erfolgt dies noch "statisch". D.h. wir legen ein bestimmtes Team aus der Aufgabenverwaltung fest, für das alle Aufgaben - geordnet nach Projekten - zurückgegeben werden.

Im zweiten Anwendungsfall erfolgt das Zurückgeben der Werte "dynamisch". D.h. der Anwender bzw. Konsument des API-Endpunkts kann ein beliebiges Team aus der Aufgabenverwaltung eingeben bzw. auswählen. Anschließend werden die Aufgaben dieses Teams- geordnet nach Projekten - zurückgegeben.

Wir setzen für die hier beschriebenen Einschränkungen bzw. Selektionen einmal den Filter-Dialog und einmal den Dialog-Schritt "Query-Parameter" ein.

Vorbereitende Tätigkeiten

Das vorliegende "Advanced Tutorial" baut auf dem Tutorial "API-Endpunkt für eine Applikation erstellen" auf. Es ist hilfreich, den dort beschriebenen Anwendungsfall zuerst nachzustellen.

Für das Advanced Tutorial sind die gleichen vorbereitenden Tätigkeiten durchzuführen wie für das Tutorial "API-Endpunkt für eine Applikation erstellen" :

Demoportal anlegen oder Applikation "Aufgabenplanung" in bestehendes Portal importieren

Das vorliegende Tutorial beschreibt das Erstellen der REST-API-Schnittstelle auf der Basis des Intrexx Demoportals. Wie Sie ein neues Portal anlegen und dabei das Intrexx Demoportal als Vorlage verwenden können, können Sie in folgendem Abschnitt nachlesen: Intrexx Demoportal als Portalvorlage verwenden

Alternativ können Sie auch die Applikationsvorlage "Aufgabenplanung in ein bestehendes Portal importieren. Die entsprechende Vorgehensweise wird in folgendem Abschnitt beschrieben: Online-Applikationsvorlagen importieren.
Benutzer "David Winter" anlegen.

Im Tutorial heißt der Benutzer, der die REST-API-Schnittstelle verwenden soll David Winter. Er hat die Rolle "Benutzer".

Im Intrexx Demoportal ist dieser Benutzer standardmäßig angelegt.
Postman herunterladen oder online nutzen

Installieren Sie den Postman Client oder nutzen Sie "Postman for the Web".
- https://www.postman.com/
- https://web.postman.co

Aufgaben eines bestimmten Teams ermitteln

Anforderung

Sie möchten sich einen Überblick über alle Aufgaben Ihres Teams verschaffen. Hierfür möchten Sie die folgenden Informationen abfragen:

Titel des Teams
Titel des Projekts
Titel der Aufgaben
Status der Aufgaben

Die Datengruppe "Aufgabe" enthält alle erforderlichen Datenfelder, um die gewünschten Informationen abzufragen. Dabei gehört das Datenfeld "Titel" unmittelbarer zur Datengruppe "Aufgabe". Es beinhaltet den Titel der Aufgabe. Die anderen Datenfelder sind in der Datengruppe "Aufgabe" aus den Datengruppen "Team", "Projekt" und "Status" referenziert.

Vorgehensweise

Schritt-für-Schritt

Um sich einen Überblick über alle Aufgaben des Teams "Sales" zu machen, gehen Sie wie folgt vor:

Erstellen Sie einen neuen Endpunkt und vergeben Sie für diesen einen sprechenden Namen.
Klicken Sie auf "Datengruppen-Endpunkt".
Klicken Sie auf "Weiter".

Sie gelangen auf den Dialog-Schritt "Datengruppenauswahl".
Wählen Sie im Auswahlfeld "Aktion" den Wert "Mehrere Datensätze lesen" aus.
Wählen Sie im Auswahlfeld "Applikation" den Wert "(aktuelle Applikation)" aus.
Wählen Sie im Auswahlfeld "Datengruppe" den Wert "Aufgabe" aus.
Klicken Sie auf das - Icon.
Deaktivieren Sie das Kontrollkästchen "(PK) (S) (ID) <string>

Datenfelder auswählen

Wählen Sie im Dialogfenster "Datenfelder hinzufügen" die folgenden Datenfelder aus:
- Titel <string>
- Projekt - Titel <string>
- Status - Titel <string>
- Team - Titel <string>
Für eine bessere Lesbarkeit der Rückgabewerte und der Swagger-Dokumentation empfiehlt es sich, die Rückgabewerte umzubenennen.

Für dieses Tutorial wurden die Rückgabewerte folgendermaßen umbenannt:
- title (Titel <string>) → taskTitle
- ref4125cc5b (Titel <string>) → taskStatus
- ref0542049e (Titel <string>) → teamTitle
- ref5477b5f9 (Titel <string>) → titleProject
Namen von referenzierten Datenfeldern

Die Namen der in der Datengruppe "Aufgabe" referenzierten Datenfeldern entsprechen dem Namen der Referenzfelder. Diese können Sie sich im Intrexx-Expert-Modus (Expert-Modus) anzeigen lassen. Markieren Sie hierfür die Datengruppe. Führen Sie einen Rechtsklick aus. Wählen Sie im Kontextmenü "Datenfelder anzeigen" aus. Markieren Sie das referenzierte Datenfeld. Führen Sie einen Rechtsklick aus. Wählen Sie im Kontextmenü "Eigenschaften" aus. Wechseln Sie auf die Registerkarte "Expert".

Datenfelder nacheinander hinzufügen

Sie können die Datenfelder nacheinander hinzufügen und jeweils das neu hinzugekommene Feld umbenennen.
Klicken Sie auf "Weiter".
Vergeben Sie einen statischen Pfad-Parameter.

In diesem Tutorial vergeben wir den Namen "GetSalesTasks".
Klicken Sie auf "Weiter".
Überspringen Sie den Dialog-Schritt "Query-Parameter" und klicken Sie auf "Weiter".

Sie gelangen in den Dialog-Schritt "Filter und Sortierung".

Filter auf Team "Sales"

Im Bereich "Filter" legen wir fest, dass nur die Aufgaben des Teams "Sales" abgefragt werden.
Klicken Sie auf das - Icon.

Das Dialogfenster "Eigenschaften des Filterausdrucks" wird angezeigt.
Wählen Sie die Option "Benutzerdefiniert" und geben Sie im Eingabefeld "Zeichenkette" die Zeichenkette "Sales" ein.
Klicken Sie auf "OK".

Sie gelangen zurück in den Dialog-Schritt "Filter und Sortierung".

Rückgabewerte sortieren

Abschließend soll noch die Sortierung der Rückgabewerte festgelegt werden. Diese sollen nach dem Projekt sortiert werden, zu dem sie gehören.
Löschen Sie zunächst die standardmäßig vorliegende Sortierung nach "Titel <string>". (Dies entspräche der Sortierung nach dem Titel der Aufgabe.)
Klicken Sie auf das - Icon.
Wählen Sie "Aufgabe" > "Projekt - (REF-PK) ID <string>" aus.
Klicken Sie auf "Fertigstellen".
Klicken Sie auf das - Icon (Applikation vollständig veröffentlichen).

Weiteres Vorgehen

Verfahren Sie nun wie gewohnt. Vergeben Sie die Rechte am API-Endpunkt, erzeugen Sie einen API-Key bzw. aktivieren Sie einen vorhanden API-Key für den API-Endpunkt, erstellen Sie die Swagger-Dokumentation und importieren Sie sie in Postman.

Nach dem Ausführen des Requests wird die folgende JSON-Datei zurückgegeben.

JSON-Datei

{
    "information": {
        "limit": 150,
        "offset": 0,
        "orderBy": [
            {
                "field": "F34E2EC1891D7EEC1C1D3271CA53E700F3CD257F",
                "order": "asc"
            }
        ]
    },
    "data": [
        {
            "taskTitle": "Einarbeitung - Workshop planen",
            "taskStatus": "Erledigt",
            "teamTitle": "Sales",
            "titleProject": "Neues ERP"
        },
        {
            "taskTitle": "Interessentenmodul verbessern",
            "taskStatus": "Todo",
            "teamTitle": "Sales",
            "titleProject": "Neues ERP"
        },
        {
            "taskTitle": "Datenübernahme",
            "taskStatus": "In Bearbeitung",
            "teamTitle": "Sales",
            "titleProject": "Neues ERP"
        },
        {
            "taskTitle": "Artikelliste prüfen",
            "taskStatus": "Todo",
            "teamTitle": "Sales",
            "titleProject": "Neues ERP"
        }
    ]
}

Aufgaben eines beliebigen Teams ermitteln

Anforderung

Sie möchten sich einen Überblick über die Aufgaben eines beliebigen Teams verschaffen. Sie möchten hierfür den Titel des jeweiligen Teams in ein Eingabefeld eingeben oder einem Auswahlfeld auswählen und anschließend die folgenden Informationen zurückgeliefert bekommen:

Titel des Teams
Titel des Projekts
Titel der Aufgaben
Status der Aufgaben

Vorgehensweise

Die meisten Schritte bei dieser Anforderung entsprechen den Schritten beim Ermitteln der Aufgaben für ein bestimmtes Team. Die zentrale Änderung besteht darin, statt einer statischen Anfrage eine dynamische Anfrage zu erstellen, bei der der Anwender das Team eingeben oder auswählen kann, für das er die Aufgaben ermitteln möchte. Dies wird im Dialog-Schritt "Query-Parameter" eingerichtet. Gleichzeitig entfällt das Filtern auf die Zeichenkette "Sales" im Dialog-Schritt "Filter und Sortierung".