docs.testware | testWare API Endpunkte

Endpunkt

Adresse des Endpunktes ohne Domainnamen. Damit der Zurgiff stattfinden kann muss der komplette mit Domainnamen als Adresse verwendet werden. Beispiel: der Endpunkt /status würde mit der aktuellen Version und dem Domainnamen https://testware.io/api/v1 als komplette Adressse https://testware.io/api/vi/status lauten.

Variable(n)

Wenn zur Identifizierung eines Objektes eine Variable benötigt wird wird dies in { } angegeben.

Beispiel:

Für den Endpunkt /location/{id} ist id die Variable. Ein Objekt mit der id 1 wird dann als /location/1 abgerufen.

Möchte man die Anzahl der Datensätze pro Abruf begrenzen so kann man hinter dem Endpunkt ein ?per_page=x anfügen. x steuert hierbei die Anzahl der Datensätze pro Seite.

Beispiel des Endpunktes für Lagerfächer /compartment?per_page=10

{
    "data": [
        {
            "id": 1,
            "created": "2021-01-06 22:23:44",
            "updated": "2021-01-06 22:23:44",
            "label": "SP.7-ru0rxn",
            "uid": "c9903a08-728a-3067-bf79-ec24ab757713",
            "name": "quos-repudiandae-et-quia-quas-ad-voluptatem-ratione",
            "description": null,
            "type_id": 2,
            "room_id": 9
        },
        {...}
    ],
    "links": {
        "first": "https://testware.io/api/v1/compartment?page=1",
        "last": "https://testware.io/api/v1/compartment?page=5",
        "prev": null,
        "next": "https://testware.io/api/v1/compartment?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "https://testware.io/api/v1/compartment",
        "per_page": "10",
        "to": 10,
        "total": 48
    }
}

Das Antwort-Schema der API wird in diesem Fall über drei weitere Elemente data links und meta erweitert.

data enthält die Datensätze der aktuellen Seite

links enthält Navigation-Links

meta enthält Daten, wie die aktelle Seite current_page oder die Gesamtzahl an Datensätzen total

Aufgabe

Kurze Beschreibung der Aufgabe des Endpunktes.

Methode

Verwendetes Übertragungsprotokoll GET, POST, PUT oder DELETE

JSON

JSON Schema für die Antwort der API oder das notwendige Schema zum Senden von Daten zur API.
Beispiel für die Antwort des Endpunktes /status mit der GET Methode:


{
    "status": "OK"
}

Hinweis

In dem Schema repräsentiert {...} das weitere Datensätze möglich sein können.

Hinweis

In dem Schema zum Senden von Daten werden alle Felder aufgelistet. Diese können auch optionale Felder enthalten, welche für eine erfolgreiche Transaktion nicht erforderlich sind.

Feldtyp

Felder werden für die Übertragung vom Clienten zur API verwendet. Diese können verschiedene Typen repräsentieren:

Typ	Name	Beispiel
Text	STRING	Hallo Welt!
Ganze Zahl	INTEGER	10
Dezinmalzahl	FLOAT	1.3
Boolscher Wert (Wahr/Falsch)	BOOLEAN	true oder false
Objekt	OBJECT	Sammlung von weiteren Feldern mit { } umschlossen. `{ "Objekt" :{ "feldname" : "wert", "feldname 2" : "wert 2" } }`

Hinweis

Manche Felder haben einen voreingestellten Wert. Dieser wird mit DEFAULT gekennzeichnet. Wenn ein Feld explizit leer gelassen werden soll ist der Wert null einzutragen.

Felder

Listet alle Felder mit dem entsprechendem Typ . Sollten Felder zwingend notwendig sein, werden diese gesondert als Erforderliche Daten ausgewiesen.

Felder die innerhalb eines OBJECT Typs werden mit dem Namen des Objektfeldes mit einem . als Präfix versehen.

Beispiel für folgendes Objekt:


{
    "location" : {
        "name" : "Werk 1"
    }
}

Das Feld für name wird mit location.name referenziert.

Wichtig für das Anlegen von Datensätzen

Ist ein Feld vom Typ OBJECT angegeben, sind zwei verschiedene Möglichkeiten verfügbar:

Angabe als Objekt

Verwendet man das Feld als Objekt muss die entsprechende Struktur angegeben werden. Das System prüft, ob ein Datensatz mit der entsprechenden Referenz existiert und legt gegebenefalls einen neuen Datensatz an.

Angabe mit Referenz-ID

Ist die Referenz-ID bekannt, so kann diese direkt angegeben werden. Hierzu muss dem Feldnamen ein _id angehängt werden.

Aus dem obigen Beispiel würde:


{
    "location_id" : 1
}

Hinweis

Sind keine Felder zur Übertragung zur API notwendig bleibt die Spalte leer.