Domains & URLs

Über diese Ressource können sowohl ONE-Site-URLs generiert als auch benutzerdefinierte Subdomains (Slugs) auf Validität und Verfügbarkeit geprüft werden.

Es ist möglich, eine ONE Site unter einer individuellen Domain zu betreiben. Diese kann z. B. vom Inhaber (Immobilenmakler) bereits vorab bei einem beliebigen Anbieter registriert worden sein.

Unabhängig davon ist aber jede neu angelegte ONE Site zunächst unter einer Subdomain-URL verfügbar. Die zugehörige Second-Level-Domain ist hierbei abhängig vom Provider, Standard ist immonex.one.

Subdomains werden nachfolgend als Slugs bezeichnet. Lautet die vollständige URL bspw. https://abc-xyz-immo.immonex.one/ ist abc-xyz-immo der Slug.

Endpunkte

GET https://api.immonex.one/wp-json/one-api/v2/site-urls/:slug (Slug prüfen/anpassen)
POST https://api.immonex.one/wp-json/one-api/v2/site-urls (Slug/URL generieren)

Slug prüfen/anpassen

Ein gültiger Slug besteht ausschließlich aus Kleinbuchstaben, Zahlen sowie Bindestrichen als Trennzeichen (in Sonderfällen auch Unterstriche) und hat eine Länge zwischen drei und 64 Zeichen.

Über den folgenden Endpunkt kann ein angegebener Slug gleichzeitig validiert und “slugifiziert” werden. Sprich, eine Angabe wie “ABC ÖÄ Xyz Immo” könnte automatisch in abc-xyz-immo konvertiert werden und wäre somit gültig.

Neben der reinen Syntax wird auch die Verfügbarkeit geprüft: Ist bereits eine ONE Site mit identischem Slug und gleicher Second-Level-Domain vorhanden, ist der übermittelte Slug ungültig.

Endpunkt
GET https://api.immonex.one/wp-json/one-api/v2/site-urls/:slug

Request (Beispiel)
GET https://api.immonex.one/wp-json/one-api/v2/site-urls/ABC-Xyz Immo

Im Erfolgsfall wird der (eventuell angepasste) valide Slug als Unterelement des Elements data zurückgeliefert.

Response (Erfolg)
200 OK

1
2
3
4
5
6
7

{
    "code": "valid",
    "data": {
        "slug": "abc-xyz-immo",
        "valid": 1
    }
}

Response (ungültiger/vergebener Slug)
422 Unprocessable Entity

1
2
3
4
5
6
7
8
9

{
    "code": "invalid_or_unavailable_entity",
    "message": "Slug ungültig oder vergeben.",
    "data": {
        "slug": "abc-xyz-immo",
        "valid": 0,
        "status": 422
    }
}

Slug/URL generieren

Neben der Prüfung/Anpassung eines benutzerdefinierten Slugs ist es auch möglich, einen solchen im Rahmen der automatisierten Generierung einer Site-URL anhand von Firma und Ort mit erstellen zu lassen.

Pflichtangabe ist hierbei der Name bzw. die Firmierung des Unternehmens, für die eine ONE Site angelegt wird. Diese Angabe wird im Payload-Element company(Request-Body) übermittelt. Die zusätzliche Angabe des Ortes (city) ist optional. Da dieser bei der Generierung der URL mit einbezogen wird, sollte er aber immer mit übertragen werden.

Um die Slugs/URLs möglichst kurz zu gestalten, wird der Begriff “Immobilien” ausgefiltert. Ist bereits eine ONE Site mit dem anschließend generierten Slug vorhanden, wird zunächst der Ort ergänzt. Ist auch diese URL nicht mehr verfügbar, erfolgt eine Nummerierung, bis eine freie URL ermittelt wurde.

Endpunkt/Request (Beispiel)
POST https://api.immonex.one/wp-json/one-api/v2/site-urls

1
2
3
4

{
	"company": "ABC Xyz Immo",
	"city": "Demostadt"
}

Response (Erfolg)
200 OK

1
2
3
4
5
6
7
8
9

{
    "data": {
        "protocol": "https://",
        "slug": "abc-xyz-immo",
        "domain": "abc-xyz-immo.immonex.one",
        "url": "https://abc-xyz-immo.immonex.one",
        "sld": "immonex.one"
    }
}

Response (Firma fehlt)
400 Bad Request

1
2
3
4
5
6
7
8

{
    "code": "missing_params",
    "message": "Es wurden nicht alle erforderlichen Parameter übermittelt.",
    "data": {
        "missing": "company",
        "status": 400
    }
}