Einleitung

Ouruka ist ein cloud-nativer REST-API-Dienst zur Generierung eindeutiger, strukturierter IDs. Er richtet sich an Entwickler und Systemintegratoren, die in ihren Anwendungen zuverlässig einzigartige Identifikatoren benötigen — ohne selbst Logik für Zähler, Datumsstempel oder Eindeutigkeitsgarantien implementieren zu müssen.

Typische Einsatzbereiche

• Produktinformationssysteme (PIM): Einheitliche Artikel- und Produktnummern über mehrere Verkaufskanäle hinweg.
• ERP-Systeme: Belegnummern, Auftragsnummern und Lieferscheinnummern in einheitlichem Format.
• Webshops und E-Commerce: Bestellnummern, Kundennummern und Transaktions-IDs.
• Logistik: Sendungsnummern, Paletten-IDs und Versandlabels.
• Healthcare: Patientenakten-Nummern, Proben-IDs und Vorgangsnummern.
• Produktion und Fertigung: Seriennummern, Chargenbezeichnungen und Qualitäts-IDs.

Ouruka läuft produktiv unter ouruka.com und ist von überall erreichbar. Die vollständige API-Dokumentation mit interaktivem Testbereich ist unter ouruka.com/swagger/ verfügbar.

Schnellstart

In drei Schritten zur ersten generierten ID:

1. Paket wählen & registrieren

   Wählen Sie ein Paket (Discovery, Solar, Galaxy oder Universe) und schließen Sie die Registrierung ab. Das System legt automatisch Ihren persönlichen Tenant an — Ihren isolierten Bereich im Ouruka-System — und stellt Ihnen dabei einmalig einen api_key aus.

   Den API-Key sicher aufbewahren — er wird nur einmalig ausgegeben und ist für alle weiteren API-Aufrufe erforderlich.

2. Schema erstellen

   Ein Schema definiert das Format der IDs. Sie legen fest, aus welchen Bausteinen — Datum, Zähler, feste Zeichen, Variablen — sich eine ID zusammensetzt.

   HTTP Request

   POST /v2/schema
   X-API-KEY: <Ihr API-Key>
   
   {
     "name":    "bestellnummer",
     "pattern": "ORD-{DATE:YYYY}{DATE:MM}-{COUNTER:5}"
   }

   Dieses Pattern erzeugt IDs wie ORD-202503-00001.

3. ID generieren

   Mit dem Namen des Schemas rufen Sie die nächste ID ab. Ouruka stellt sicher, dass jede generierte ID eindeutig ist — auch bei parallelen Anfragen.

   HTTP Request

   POST /v2/id/generate
   X-API-KEY: <Ihr API-Key>
   
   {
     "schema": "bestellnummer"
   }

   Response 200 OK

   {
     "id": "ORD-202503-00042"
   }

Authentifizierung

Alle Endpunkte, die Daten lesen oder schreiben, erfordern einen gültigen API-Key. Dieser wird als HTTP-Header übermittelt:

X-API-KEY: <Ihr API-Key>

Der API-Key wird bei der Registrierung automatisch vom System ausgegeben. Er identifiziert Ihren Tenant eindeutig und steuert den Zugriff auf alle Ihre Schemas, Zähler und ID-Historien.

ID-Generierung mit Schemas

Schemas sind das Herzstück von Ouruka. Sie definieren das exakte Format einer ID durch ein Pattern — eine Zeichenkette, in der feste Textelemente mit dynamischen Platzhaltern kombiniert werden.

ART-{DATE:YY}{DATE:MM}-{COUNTER:4}
      ↓
ART-2503-0017

{VAR1}      — Wert direkt eingefügt
{VAR1:-}    — Wert mit Bindestrich als Separator
{VAR2:/}    — Wert mit Schrägstrich als Separator

Zufalls-IDs (UID)

Neben strukturierten Schema-IDs bietet Ouruka zufallsbasierte Unikate. UIDs enthalten keine semantischen Informationen wie Datum oder Zähler — sie sind rein eindeutig und eignen sich für Tokens, API-Keys und alle Szenarien, in denen Anonymität und Zufälligkeit gefragt sind.

POST /v2/uid/numeric

POST /v2/uid/alpha

String-Konvertierung (Keyify)

POST /v2/keyify

Keyify konvertiert beliebige Freitext-Strings in URL-sichere, einheitlich formatierte Schlüssel. Typische Anwendungsfälle sind URL-Slugs, Datenbankschlüssel, technische Bezeichner oder suchmaschinenfreundliche Produkt-URLs aus natürlichsprachlichen Eingaben.

Transformationen

• Leerzeichen werden durch Bindestriche (-) ersetzt
• Sonderzeichen werden entfernt oder umgewandelt
• Groß- und Kleinschreibung wird vereinheitlicht (Lowercase)
• Deutsche Umlaute werden aufgelöst: ä→ae, ö→oe, ü→ue, ß→ss
• Mehrfach aufeinanderfolgende Bindestriche werden bereinigt

Umlaut-Referenz

Praxisbeispiele

History

Ouruka protokolliert jede generierte ID in einer History-Liste, die pro Schema abrufbar ist. Gespeichert werden die generierte ID, der Zeitstempel (UTC) sowie optionale Metadaten.

Die History ermöglicht es, nachzuvollziehen, welche IDs wann generiert wurden — nützlich für Audits, Fehleranalysen und Workflows, die auf Vollständigkeit prüfen.

GET /v2/history
X-API-KEY: <Ihr API-Key>

Speicherdauer nach Paket

FAQ

Swagger / API-Referenz

Die vollständige technische API-Dokumentation ist interaktiv über den Swagger-Bereich erreichbar — direkt im Browser, ohne externe Tools.

• Vollständige Endpunkt-Übersicht: Alle verfügbaren API-Endpunkte mit Methoden, Pfaden und Beschreibungen.
• Request- und Response-Schemas: Genaue Definitionen aller Ein- und Ausgabefelder, Datentypen und Pflichtfelder.
• Interaktives Testen: Endpunkte direkt im Browser mit eigenem API-Key aufrufen.
• Beispiel-Requests und -Responses: Konkrete Beispiele für typische Anwendungsfälle.
• Fehlercodes: Dokumentation aller HTTP-Fehlercodes und deren Bedeutung.

Um den Swagger-Bereich zu nutzen, klicken Sie auf Authorize und tragen Sie Ihren X-API-KEY ein.