Endpunkte und statische Antworten

Eine Simulation stellt Endpunkte bereit: Jeder ist eine Methode plus ein Pfad und antwortet unter der URL der Simulation. Es gibt zwei Quellen. OpenAPI-Endpunkte kommen aus deiner Spec und antworten mit Daten, die aus ihren Schemas generiert werden. Einen statischen Endpunkt definierst du selbst: Methode und Pfad wählen, den Antwortbody eintippen, und Aufrufer bekommen genau diesen Body zurück.

Die Endpunkte-Ansicht

Öffne eine Simulation und sie startet auf Endpunkte. Dort stehen beide Arten zusammen, gruppiert nach Service.

• Der Schalter schaltet einen Endpunkt an oder aus. Ein ausgeschalteter Endpunkt bleibt beim nächsten Deploy außen vor.
• Der Chip neben dem Schalter ist der Inhaltstyp eines statischen Endpunkts: JSON, TEXT, HTML oder XML.
• Latenz- und Fehlerregeln stehen ebenfalls auf der Zeile, wie 300ms und 10% 503 oben.
• Klick auf eine Zeile öffnet ihre Einstellungen.

Suche und Service-Filter sitzen über der Liste. Lange Listen blättern mit 50 Endpunkten pro Seite.

Zwei Arten von Endpunkten

OpenAPI-Endpunkte folgen einem Vertrag. Die Spec definiert die Form jeder Antwort, der Body ist in der App darum schreibgeschützt, und jeder Aufruf generiert frische Daten, die zum Schema passen. Um sie zu ändern, änderst du die Spec.

Siehe OpenAPI-Spec hochladen und aktualisieren.

Ein statischer Endpunkt hat keinen Vertrag. Keine Datei hochzuladen, kein Schema einzuhalten: Die Antwort ist der Text im Editor, und ein Aufruf bekommt Status 200 mit genau diesem Text. Damit ist er der schnellste Weg, eine Route auf die Leitung zu bringen:

• eine Abhängigkeit mocken, die keine OpenAPI-Spec hat,
• die eine exakte Payload liefern, auf die ein Test prüft,
• einen Healthcheck, einen Config-Blob oder eine kleine HTML-Seite beantworten,
• eine Route einer Spec auf eine feste Antwort pinnen, während der Rest generiert bleibt.

So entsteht die URL

Eine Simulation antwortet unter <domain>/app/<deine-org>/<slug>, und jeder Endpunkt liegt darunter. Ein statischer Endpunkt wird unter seinem Pfad bedient, so wie du ihn eingibst; GET /health von oben antwortet unter:

https://api.mockz.io/app/docs-shots/tidy-valley/health

OpenAPI-Endpunkte antworten stattdessen unter dem Mount-Pfad ihrer Spec: Petstores GET /pets, gemountet unter petstore, antwortet unter /petstore/pets.

Regeln für einen statischen Pfad:

• Er beginnt mit /, endet ohne / und passt in 256 Zeichen.
• Ein Segment in der Form {name} matcht jeden Wert: /users/{id}/orders antwortet für jede id.
• Ein Endpunkt pro Methode und Pfad. Derselbe Pfad mit zwei Methoden sind zwei Endpunkte.

Statische Endpunkte gruppieren sich über ihr erstes Pfadsegment zu Services: /v1/greeting und /v1/ping bilden von allein den Service v1. Es gibt nichts einzurichten; der Service erscheint mit seinem ersten Endpunkt und hat eigene Service-Einstellungen.

Statischen Endpunkt hinzufügen

Klick in Endpunkte auf Hinzufügen und wähle Statischer Endpunkt.

Der Endpunkt wird sofort als GET /new mit leerem JSON-Body angelegt und öffnet sich zum Bearbeiten:

• Methode: GET, POST, PUT, PATCH oder DELETE.
• Inhaltstyp: application/json, text/plain, text/html oder application/xml.
• Pfad: wo er antwortet.
• Der Editor hält den Antwortbody.

Jede Änderung speichert beim Tippen; es gibt keinen Speichern-Button.

Antwort ändern

Endpunkt öffnen, Body bearbeiten, auf Deploy klicken. Wenige Sekunden später liefert dieselbe URL die neue Antwort. Aufrufer merken nichts: URL, Methode und Inhaltstyp passen weiter, nur die Payload hat sich geändert. Braucht der nächste Testfall eine andere Antwort, änderst du sie hier statt im Code.

OpenAPI-Endpunkt überschreiben

Ein statischer Endpunkt mit derselben Methode und demselben Pfad wie ein OpenAPI-Endpunkt übernimmt die Route. Die Liste markiert das Paar: Die statische Zeile bekommt den Chip überschreibt, die OpenAPI-Zeile ist ausgegraut mit überschrieben.

Das ist für die Spec mit hundert Endpunkten, bei der eine Antwort deine sein muss. Ohne Überschreiben müsstest du die Spec forken und die ganze Kopie für diese eine Änderung pflegen. Hier bleibt die Spec wie hochgeladen: statischen Endpunkt auf dem vollen Pfad anlegen, Payload einfügen, deployen. Die anderen neunundneunzig generieren weiter aus ihren Schemas, und ein späterer Spec-Tausch lässt das Überschreiben stehen.

Der überschriebene OpenAPI-Endpunkt ist nicht weg. Lösche den statischen Endpunkt oder verschiebe seinen Pfad, und er antwortet wieder.

Latenz und Fehler

Ein statischer Endpunkt kann absichtlich verzögern und fehlschlagen. Öffne ihn und wechsle auf den Tab Verhalten.

• Vor Antwort warten hält die Antwort für die angegebene Zeit zurück.
• Fehlerinjektion gibt für einen Anteil der Anfragen einen Fehlerstatus zurück: Die Regel 10% -> 503 lässt einen von zehn Aufrufen fehlschlagen. Pro Anfrage wird eine Zahl von 1 bis 100 gewürfelt und die Regel mit dem niedrigsten passenden Prozent gewinnt; Regeln stapeln sich also nicht, das höchste Prozent ist die Gesamtfehlerquote.

Die übrigen Aufrufe antworten mit Status 200 und dem Body.

Ein statischer Endpunkt ist eine Datei

Unter der Haube ist jeder statische Endpunkt eine Datei, und es gibt kein Format zu lernen: Die Ordnerstruktur ist die URL.

• Jedes Pfadsegment ist ein Ordner: /hello-world/v1 sind die Ordner hello-world/v1/.
• Die Methode ist ein weiterer Ordner, kleingeschrieben: get/, post/.
• Der Body ist die index-Datei darin, und die Endung bestimmt den Inhaltstyp: .json, .txt, .html oder .xml.

POST /hello-world/v1 ist also die Datei hello-world/v1/post/index.json. Lies eine URL und du kennst die Datei; lies den Baum und du kennst die API.

services/
  hello-world/
    v1/
      get/
        index.json    # GET /hello-world/v1
      post/
        index.json    # POST /hello-world/v1

Lässt du den Methodenordner weg, antwortet die Datei auf GET. Ein Ordner namens {petId} matcht jeden Wert, genau wie in der App.

Der Editor in der App schreibt dieses Layout beim Deploy für dich. Du kannst es auch selbst schreiben und statische Endpunkte neben deinem Code versionieren: Eine portable Simulation fährt dieselbe Ordnerstruktur direkt von deiner Platte, und die GitHub Action deployt sie aus einem Repo. Das Portable-Template liefert genau diesen hello-world-Service zum Starten.

Mehr als ein fester Body

Statisch beschreibt nur die Antwort. Auf der Leitung verhalten sich diese Endpunkte wie alle anderen:

• Der Tab Upstream kann einen auf ein echtes Backend zeigen lassen, geerbt vom Service oder für den einzelnen Endpunkt überschrieben.
• Jeder Aufruf landet im Verlauf.
• Der deployte API-Explorer listet ihn neben den OpenAPI-Endpunkten.