Getting Started

Dieses Kapitel führt dich von „nichts installiert“ zu „erster Request“ und gibt dir Best Practices an die Hand.

Voraussetzungen

Node.js 18+ (Empfehlung: LTS)
Package Manager deiner Wahl (pnpm, npm, yarn)
Serverseitige Umgebung zum Ausführen deiner Integrationen

API-Key erzeugen

Im Admin-Bereich unter API Keys anlegen. Der Key wird serverseitig als Secret gespeichert. Im Request-Header verwendest du x-api-key.

ENV konfigurieren

Lege ein Secret in deiner Runtime/Pipeline an, z. B.MAILER_API_KEY. Beispiel für lokale Entwicklung:

MAILER_API_KEY=
# optional für Distance/ETA via GraphHopper
NEXT_GRAPHHOPPER_API_KEY=

Erster Request

Die öffentlichen Endpunkte erwarten POST und JSON.

curl -X POST "https://dev.nuvisphere.de/api/address/geocoding"   -H "Content-Type: application/json"   -H "x-api-key: $MAILER_API_KEY"   -d '{"q":"Alexanderplatz"}'

const res = await fetch("https://dev.nuvisphere.de/api/address/geocoding", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.MAILER_API_KEY!,
  },
  body: JSON.stringify({ q: "Alexanderplatz" }),
});
if (!res.ok) throw new Error('Request failed ' + res.status);
const json = await res.json();

Next.js Beispiele

// app/api/geocode/route.ts
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const body = await req.json();
  const res = await fetch("https://dev.nuvisphere.de/api/address/geocoding", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.MAILER_API_KEY!,
    },
    body: JSON.stringify(body),
  });
  return new NextResponse(await res.text(), { status: res.status });
}

"use server";
export async function geocode(q: string) {
  const res = await fetch("https://dev.nuvisphere.de/api/address/geocoding", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.MAILER_API_KEY!,
    },
    body: JSON.stringify({ q }),
  });
  if (!res.ok) throw new Error("Failed");
  return res.json();
}

Beispiel-Screenshot

Platzhalter für UI-Screenshots (ersetzbar durch echte Bilder):

Auth & Sicherheit

API Keys niemals clientseitig verwenden.
Rate Limiting und Logging auf Applikationsebene aktivieren.
Secrets in CI/CD als Encrypted Variables pflegen.