Website-API#

Lesen und schreiben Sie den Inhalt einer NAMES LEGAL-Website über HTTPS: Dienstleistungen, Projekte, Blogbeiträge, Teammitglieder, Veranstaltungen, Stellenangebote, FAQ und mehr. Die API ist Teil des Add-ons API-Zugang der Website.

Schnellstart#

1. Aktivieren Sie in der Konsole der Website unter Add-ons & Abonnement das Add-on API-Zugang.
2. Module → API: Erstellen Sie einen Schlüssel. Kopieren Sie ihn jetzt — er wird nur einmal angezeigt.
3. Rufen Sie die API auf:

KEY="nlk_3fa9c2d1_Jx0..."
curl -H "Authorization: Api-Key $KEY" "https://ecolehorizon.names.legal/api/v1/team/?lang=fr"

{
  "count": 12,
  "next": "https://ecolehorizon.names.legal/api/v1/team/?lang=fr&page=2",
  "previous": null,
  "results": [
    {"id": 4, "first_name": "Awa", "last_name": "Diop", "position": "Mathematics teacher",
     "profile_image": "https://ecolehorizon.names.legal/media/demo/team/awa.jpg",
     "updated_at": "2026-09-20T08:12:44+02:00"}
  ]
}

Basis-URL#

https://<site>/api/v1/

<site> ist die eigene Adresse der Website (ecolehorizon.names.legal oder ihre eigene Domain). Es gibt kein Sprachpräfix im Pfad. v1 ist die einzige Version; eine grundlegende Änderung würde als v2 daneben eingeführt.

Die Root-URL listet jede Sammlung auf. Eine interaktive Referenz (Swagger) und das OpenAPI-Schema sind auf jeder Website verfügbar:

Authentifizierung#

1. Der Website-Inhaber aktiviert das Add-on API-Zugang.
2. In der Konsole, unter Module → API, erstellt er einen Schlüssel und wählt dessen Geltungsbereich. Der vollständige Schlüssel wird einmal angezeigt; gespeichert werden nur ein Präfix und ein Hash.
3. Senden Sie den Schlüssel mit jeder Anfrage.

GET /api/v1/services/ HTTP/1.1
Host: ecolehorizon.names.legal
Authorization: Api-Key nlk_3fa9c2d1_Jx0...

Authorization: Bearer <key> und X-Api-Key: <key> werden ebenfalls akzeptiert. Schlüssel sehen aus wie nlk_<8 hexadezimale Zeichen>_<secret>.

Geltungsbereiche#

Der Geltungsbereich gilt für den gesamten Schlüssel; es gibt keinen Geltungsbereich pro Sammlung. Ein Schlüssel kann jederzeit über die Konsole widerrufen werden.

Fehler, die Ihnen begegnen können#

Sprache#

Übersetzte Felder werden jeweils in einer Sprache zurückgegeben. Wählen Sie sie mit ?lang=:

curl -H "Authorization: Api-Key $KEY" "https://ecolehorizon.names.legal/api/v1/services/?lang=fr"

Die Sprache muss eine der von der Website veröffentlichten Sprachen sein; andernfalls lautet die Antwort 400. Ohne lang wird die Standardsprache der Website verwendet. Die Antwort enthält einen Content-Language-Header.

Paginierung, Filter und Sortierung#

Listen werden nach Seitenzahl paginiert:

{
  "count": 42,
  "next": "https://ecolehorizon.names.legal/api/v1/team/?page=2",
  "previous": null,
  "results": [ ... ]
}

since macht die inkrementelle Synchronisierung günstig: Speichern Sie den Zeitpunkt Ihres letzten Aufrufs und geben Sie ihn beim nächsten Mal an.

Ratenlimits#

• 120 Anfragen pro Minute und API-Schlüssel (jeder Schlüssel hat seinen eigenen Zähler).
• Konsolen-Sitzungen: 120 pro Minute. Anonyme Aufrufe: 30 pro Minute.

Bei Überschreitung des Limits antwortet die API mit 429; warten Sie und versuchen Sie es erneut.

Sammlungen#

Jeder Eintrag ist unter <collection>/<id>/ erreichbar. Die Felder jeder Sammlung sind in der Referenz weiter unten aufgeführt.

Schreiben#

• POST erstellt, PUT ersetzt, PATCH aktualisiert einzelne Felder.
• Kategorien werden als Objekt {"id", "name", "slug"} gelesen und mit category_slug geschrieben. Ein unbekannter Slug wird abgelehnt.
• Bilder und Dateien sind in der API schreibgeschützt: Laden Sie sie in der Konsole hoch, oder lassen Sie den Datenkonnektor sie von einer URL herunterladen.
• In Rich-Text-Feldern gesendetes HTML wird bereinigt: Skripte und Event-Handler werden entfernt.

curl -X POST "https://ecolehorizon.names.legal/api/v1/faq/?lang=fr" \
  -H "Authorization: Api-Key $KEY" -H "Content-Type: application/json" \
  -d '{"question": "Quand ont lieu les inscriptions ?", "answer": "<p>Du 1er au 30 juin.</p>"}'

Einen Termin buchen#

curl -X POST "https://ecolehorizon.names.legal/api/v1/bookings/" \
  -H "Authorization: Api-Key $KEY" -H "Content-Type: application/json" \
  -d '{"item": 3, "customer_name": "Awa Diop", "customer_email": "awa@example.com",
       "date": "2026-10-02", "time": "14:30"}'

time gilt in der Zeitzone der Website. Ein Termin, der nicht mehr frei ist, wird mit 400 abgelehnt. Neue Buchungen beginnen als pending.

Rezepte#

Eine Sammlung inkrementell spiegeln#

Lesen Sie einmal alles, danach nur noch die Änderungen. Speichern Sie den Zeitpunkt Ihres letzten Laufs und übergeben Sie ihn als since.

Python

import time
import requests

BASE = "https://ecolehorizon.names.legal/api/v1/"
HEADERS = {"Authorization": "Api-Key nlk_3fa9c2d1_Jx0..."}

def fetch_all(collection, since=None, lang="fr"):
    url = f"{BASE}{collection}/"
    params = {"lang": lang, "page_size": 100, "ordering": "updated_at"}
    if since:
        params["since"] = since
    while url:
        response = requests.get(url, headers=HEADERS, params=params, timeout=15)
        if response.status_code == 429:
            time.sleep(int(response.headers.get("Retry-After", "5")))
            continue
        response.raise_for_status()
        data = response.json()
        yield from data["results"]
        url, params = data["next"], None   # "next" already carries the parameters

for member in fetch_all("team", since="2026-09-01T00:00:00Z"):
    print(member["id"], member["first_name"], member["last_name"])

JavaScript (Node.js 18+)

const BASE = "https://ecolehorizon.names.legal/api/v1/";
const HEADERS = { Authorization: "Api-Key nlk_3fa9c2d1_Jx0..." };

async function* fetchAll(collection, since, lang = "fr") {
  const first = new URL(`${BASE}${collection}/`);
  first.search = new URLSearchParams({ lang, page_size: "100", ordering: "updated_at",
                                       ...(since ? { since } : {}) });
  let url = first.toString();
  while (url) {
    const response = await fetch(url, { headers: HEADERS });
    if (response.status === 429) {
      const wait = Number(response.headers.get("Retry-After") || 5);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }
    if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
    const data = await response.json();
    yield* data.results;
    url = data.next;
  }
}

for await (const post of fetchAll("blog", "2026-09-01T00:00:00Z")) {
  console.log(post.id, post.title);
}

Einen Eintrag erstellen oder aktualisieren#

PHP

<?php
$base = 'https://ecolehorizon.names.legal/api/v1/';
$headers = ['Authorization: Api-Key nlk_3fa9c2d1_Jx0...', 'Content-Type: application/json'];

function call($method, $url, $headers, $body = null) {
    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $headers,
                            CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    $answer = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    return [$status, json_decode($answer, true)];
}

// Create an event (in French)
[$status, $event] = call('POST', $base . 'events/?lang=fr', $headers, [
    'title' => 'Journée portes ouvertes',
    'slug' => 'journee-portes-ouvertes-2026',
    'description' => '<p>Visite du campus et rencontre avec les enseignants.</p>',
    'start_date' => '2026-11-14T09:00:00+01:00',
    'end_date' => '2026-11-14T16:00:00+01:00',
    'location' => 'Campus de Genève',
]);

// Change only the location later
call('PATCH', $base . "events/{$event['id']}/?lang=fr", $headers, ['location' => 'Aula']);

lang bestimmt, in welcher Sprache ein übersetztes Feld geschrieben wird: senden Sie denselben Eintrag erneut mit ?lang=en, um die englische Version hinzuzufügen.

Fehler und Limits in der Praxis#

Referenz nach Sammlung#

Aus dem Code der API generiert: Felder, Zugriffsrechte und Abfrageparameter entsprechen immer der laufenden Plattform. Übersetzte Felder werden in der mit lang gewählten Sprache gelesen und geschrieben.

/api/v1/services/

GETPOSTPUTPATCH

• Filter slug category__slug is_featured
• search title description
• ordering order title updated_at (Standard order)

/api/v1/projects/

GETPOSTPUTPATCH

• Filter slug category__slug status is_featured
• search title description client technologies
• ordering order title project_date updated_at (Standard order)

/api/v1/blog/

GETPOSTPUTPATCH

• Filter slug category__slug status tags__slug
• search title excerpt content
• ordering published_date title updated_at (Standard -published_date)

/api/v1/team/

GETPOSTPUTPATCH

• Filter member_type is_featured
• search first_name last_name position specialties
• ordering order last_name updated_at (Standard order)

/api/v1/testimonials/

GETPOSTPUTPATCH

• Filter rating
• search name position testimonial
• ordering order rating updated_at (Standard order)

/api/v1/publications/

GETPOSTPUTPATCH

• Filter slug category__slug year is_featured
• search title authors journal abstract
• ordering order year title updated_at (Standard order,-year)

/api/v1/resources/

GETPOSTPUTPATCH

• Filter slug resource_type is_free
• search title description
• ordering order title created_at updated_at (Standard order)

/api/v1/events/

GETPOSTPUTPATCH

• Filter slug event_type is_online is_featured
• search title description location
• ordering start_date title updated_at (Standard -start_date)

/api/v1/jobs/

GETPOSTPUTPATCH

• Filter slug category__slug contract_type remote_option experience_level is_featured is_urgent
• search title description location skills_required
• ordering published_date title updated_at (Standard -published_date)

/api/v1/faq/

GETPOSTPUTPATCH

• Filter category__slug is_featured
• search question answer
• ordering order updated_at (Standard order)

/api/v1/bookable-items/

GET

/api/v1/bookings/

POST

Sicherheitsempfehlungen#

• Bewahren Sie Schlüssel auf Ihrem Server auf. Verschicken Sie niemals einen Schlüssel in einer mobilen App oder im Browser-Code.
• Verwenden Sie einen read-Schlüssel überall dort, wo Sie nicht schreiben müssen.
• Ein Schlüssel pro Integration: Das Widerrufen eines Schlüssels beeinträchtigt die anderen nicht.