Zum Hauptinhalt springen

Backend Api

Überblick​

Alle Aufrufe sind Aufrufe an eine URL unter

https://k3-api.objectcode.de/api/v1.0

Die folgenden Header sind immer zu setzen:

Content-Type: application/json
Accept: application/json
Authorization: Bearer TOKEN

Das TOKEN erhält man aus dem User-Profil.

Optional, für multilanguage-daten aber unerlässlich, ist der Language-Header:

X-Language: en

Fehlt er, wird de angenommen. Wird für ein multilanguage-Feld null übergeben, so wird das nach "" geändert. Das ist leider wegen des Verhaltens des Frameworks notwendig.

Antwortstati​

  • 200: Erfolg
  • 201: Resource erfolgreich angelegt
  • 400: Fehlende Daten oder anderweitig ungültige Anfrage
  • 401: Nicht authorisiert
  • 403: Nicht erlaubt
  • 405: Nicht authorisiert
  • 500: Unbekannter Fehler

Im Fehlerfall wird üblicherweise, aber nicht garantiert, folgende Antwort übermittelt:

  • error (boolean): true
  • msg (string): Ursache

Verfügbare Ressourcen​

Die folgenden Ressourcen stehen zur Verfügung:

  • app: Der Konfigurator
  • material: 3D-Material
  • model 3D-Modell
  • image Bild für nicht-3D-Konfiguratoren
  • group: Konfigurationsschritt
  • variable: Merkmal
  • value: Merkmals-Wert
  • rule: Regel
  • ruleitem: Regelzeile
  • article: Artikel
  • price: Preis
  • cfg: Konfiguration

Um die pro Typ zur Verfügung stehenden Attribute zu erhalten, kann man einmal eine Ressource abrufen. Die Attributnamen sind selbsterklärend:

GET https://k3-api.objectcode.de/api/v1.0/{type}?_limit=1

Aufrufe​

Resource holen​

GET .../{type}/{id}

Liefert eine Ressource anhand ihrer ID. Dies auch dann, wenn die Eltern gelöscht sind.

Parameter

  • type (string): Typ der Ressource
  • id (number): ID der Ressource

Ergebnis

  • ressource (object): Die gewünschte Ressource

Resourcen suchen​

GET .../{type}?{query}

Sucht Ressourcen anhand ihrer Attribute. Es werden auch solche Ressourcen geliefert, deren Eltern gelöscht sind.

Parameter

  • type (string): Typ der Ressource

  • query (string): Query-String a1=v1&a2=v2&a3=v3… Attribute werden nur UND-verknüpft gesucht. Es gibt folgende Operatoren:

    • a=1 Attribut a ist gleich 1
    • a=!1 Attribut a ist nicht gleich 1
    • a=[1,2] Attribut a ist in [1,2]
    • a=![1,2] Attribut a ist nicht in [1,2]
    • a=%1% Attribut a enthält 1

    Dabei gibt es die folgenden speziellen Attribute in der Query:

    • _order (string): in der Form attribut:asc|desc spezifiziert eine Sortierung
    • _offset (number): erster Datensatz, der geliefert werden soll
    • _limit (number): Anzahl der Datensätze, die geliefert werden sollen
    • _count (string): Falls "true", wird im Header 'X-Total-Count' der Antwort die Gesamtanzahl aller Treffer geliefert. (Sollte auf der ersten Seite einer Paginierung verwendet werden.)
    • _select (string): Liste der Attribute, die geliefert werden sollen, kommasepariert.

Ergebnis

  • ressourcen (array): Liste von gefundenen Objekten

Resource anlegen​

POST .../{type}

Legt eine Ressourcen an

Parameter

  • type (string): Typ der Ressource

Body

  • {} (object): Die Ressource (ohne id als Objekt)

Ergebnis

  • {} (object): Das angelegte Object inkl. id.

Viele Resourcen anlegen​

POST .../{type}/bulk

Legt Ressourcen an

Parameter

  • type (string): Typ der Ressource

Body

  • [] (array): Die zu ändernden Attribute, nicht notwendigerweise vollständig
    • {} (object): Die Ressource (ohne id als Objekt)

Ergebnis

Liste der angelegten Resourcen, inkl. id.

Resource ändern​

PUT .../{type}/{id}

Ändert eine Ressource

Parameter

  • type (string): Typ der Ressource
  • id (number): ID der Ressource

Body

  • {} (string): Die zu ändernden Attribute, nicht notwendigerweise vollständig

Ergebnis

Geänderte Ressource

Viele Resourcen ändern​

PUT .../{type}

Ändert eine Ressource

Parameter

  • type (string): Typ der Ressource

Body

  • [] (array): Die zu ändernden Attribute, nicht notwendigerweise vollständig
    • {} (object): zu ändernde Ressource
      • id (mandatorisch): ID der Ressource, die geändert werden soll
      • weitere: Die zu ändernden Attribute, nicht notwendigerweise vollständig

Ergebnis

Liste der geänderten Resourcen.

Resource löschen​

DELETE .../{type}/{id}

Löscht eine Ressource. Es handelt sich um ein soft delete. Der Datensatz verbleibt in der Datenbank, im “Trash”.

Parameter

  • type (string): Typ der Ressource
  • id (number): ID der Ressource

Ergebnis

Das gelöschte Objekt.

Viele Resourcen löschen​

PUT .../{type}/delete

Löscht alle übergebenen Ressourcen

Body

  • [] (array): Array mit Ids

Ergebnis

  • count (number): Anzahl gelöschter Ressourcen (es werden aber immer alle oder keines gelöscht)