Ga naar inhoud

Domeinen

Alle domeinen worden gerouteerd via onze hoogperformante CDN-provider, bunny. Elk domein kan worden gekoppeld door je nameservers te wijzigen of door een cname-record in te stellen.

Deze endpoints beheren de hostnames die aan WordPress-sites zijn gekoppeld. Voor registrar-operaties (een TLD registreren/verhuizen) zie Domeinregistratie. OAuth-scopes: opzoeken/queryen vereist domains:read; per-site domeinwijzigingen vereisen sites:write.

Opzoeken en query

Alle domeinen weergeven

Toon alle domeinen die voor een gebruiker toegankelijk zijn.

GET /api/domains

Params (optioneel)
  • page: Integer | paginanummer (standaard: 1)
  • per_page: Integer | records per pagina (standaard: 50, max: 100)
Geretourneerde params
  • domains: Array
    • id: String
    • hostname: String
    • site_id: String
    • site_pending_delete: Boolean | true wanneer de site van het domein soft-deleted is en op opruiming wacht
    • account_id: String
    • created_at: DateTime
    • updated_at: DateTime
    • dns_zone: Object | null | bijbehorende dns-zone
      • id: String
      • name: String
      • dnssec: Boolean
      • dnssec_data: Object (nil als dnssec = false)
      • created_at: DateTime
      • updated_at: DateTime
      • account: Object
        • id: String
        • name: String
      • nameservers: Array
    • dns_zone_records: Array | bijbehorende dns-records
      • id: String
      • record_type: Integer
      • ttl: Integer
      • value: String
      • name: String
      • priority: Integer
      • weight: Integer
      • port: Integer
      • flags: Integer
      • record_tag: String
      • comment: String
      • created_at: DateTime
      • updated_at: DateTime

Domein laden op ID

GET /api/domains/:id

Retourneert één domain-object met dezelfde velden als een lijstvermelding.

Zoeken op domeinnaam

POST /api/domains/query

Dit is een helper-endpoint om een domein te vinden zonder de ID te kennen.

De param q ondersteunt substring-matching overal in de hostname. Bijvoorbeeld:

  • Zoeken op example matcht example.com;
  • Zoeken op domain matcht mydomain.com.
Params
  • q: String

Retourneert dezelfde vorm als Alle domeinen weergeven.

Controleren of een domein beschikbaar is

POST /api/domains/available

Hiermee wordt gecontroleerd of het domein geldig is en of het al in ons systeem bestaat.

Params
  • hostname: String

Gebruik de HTTP-statuscode om beschikbaarheid/geldigheid te bepalen:

  • HTTP 200: Bestaat en is niet beschikbaar
  • HTTP 422: Geen geldig domein, of ontbrekende hostname-param.
  • HTTP 404: Bestaat niet — geldig en beschikbaar.
Geretourneerde params
  • status: String

Site-endpoints

Vergrendelde sites

Elk endpoint in dit onderdeel zoekt eerst de site op. Een site die op verwijdering wacht, is vergrendeld en geeft 403 terug met code: "pending_delete" en een delete_scheduled_at-tijdstempel — herstel de site om weer met de domeinen ervan te kunnen werken.

Een site die is opgeschort vanwege een onbetaalde factuur, is op dezelfde manier vergrendeld en geeft 402 terug met code: "service_suspended", plus een invoice-object met number en hosted_url waarmee je de klant kunt laten betalen.

Alle domeinen voor een site weergeven

GET /api/sites/:site_id/domains

Geretourneerde params
  • domains: Array
    • id: String
    • hostname: String
    • dns_zone: Object | bijbehorende dns-zone
    • dns_zone_records: Array | bijbehorende dns-records
    • created_at: DateTime
    • updated_at: DateTime

Een domein aanmaken

POST /api/sites/:site_id/domains

Koppelt een domein aan de site. Heeft de site nog geen domein, dan wordt dit het primaire domein; anders wordt het als alias toegevoegd. Inrichten gebeurt asynchroon — retourneert 202 en maakt een taak aan.

provision_method moet exact de string dns zijn om via nameservers in te richten; elke andere waarde (of weglating) wordt behandeld als cname.

Een hostname opnieuw koppelen die al aan deze site hangt, is een no-op — je krijgt het bestaande domein terug in plaats van een tweede.

Params
  • domain: String (vereist) | FQDN
  • provision_method: String | exact de string dns, anders cname
  • replace_records: Boolean | alleen bij een dns-koppeling — bevestigt dat conflicterende DNS-records die al in de zone staan, vervangen mogen worden. Zie hieronder.

DNS-conflicten

Een dns-koppeling mislukt met 422 conflicts_found wanneer de zone die wij hosten al records met een adres op die hostname bevat — in plaats van dat er concurrerende records worden weggeschreven. De reactie bevat een conflicts-array zodat je kunt tonen wat er vervangen zou worden; elk item heeft record_guid, type, host, value en site_name (null wanneer het record niet aan een site is gekoppeld). Herhaal hetzelfde verzoek met replace_records: true om die records te verwijderen en door te gaan.

Fouten

Deze fouten dragen naast errors ook een machineleesbare code. Niet elke 4xx op deze site-endpoints doet dat — een rechtenfout (403) en een onbekend domein-id bij promoveren/verwijderen/certificaat (404) geven alleen een errors-array terug. Vertak dus zowel op de statuscode als op code.

  • 400 domain_blank | domain is leeg of ontbreekt
  • 402 service_suspended | de site is opgeschort vanwege een onbetaalde factuur
  • 403 pending_delete | de site wacht op verwijdering en is vergrendeld
  • 403 (geen code) | de gebruiker achter de credential heeft geen bewerkrechten op de site
  • 422 conflicts_found | een dns-koppeling stuitte op bestaande records — herhaal met replace_records: true (de body bevat conflicts)
  • 422 hostname_in_use | de hostname is al aan een andere site binnen dezelfde facturatieaccountfamilie gekoppeld — ook aan een site die op verwijdering wacht en daarom niet meer in de lijst staat. errors noemt de site die hem vasthoudt
  • 422 invalid_domain | validatie- of eigendomsafwijzing — ook bij een dns-koppeling voor een root die een andere klant bij ons heeft geregistreerd
Geretourneerde params voor DNS (provision_method = dns)
  • id: String
  • ns1: String | eerste nameserver (van het account van de site)
  • ns2: String | tweede nameserver (van het account van de site)
Geretourneerde params voor cname (standaard)
  • id: String
  • cname: String

Een domein promoveren

PATCH /api/sites/:site_id/domains/:id

Dit neemt geen parameters aan en promoveert het aangevraagde domein tot het primaire domein. Het bestaande primaire domein wordt een alias. Retourneert 202.

Verwijderen

Hiermee wordt het domein verwijderd. Als het het primaire domein is, wordt de site bijgewerkt om de standaard tijdelijke url te gebruiken. We raden aan om eerst je nieuwe domein tot primair domein te promoveren voordat je het verwijdert. Retourneert 202.

DELETE /api/sites/:site_id/domains/:id

SSL-certificaat vooraf inrichten (externe DNS)

Verkrijg een Bunny SSL-certificaat via een DNS-01-challenge voor een hostname waarvan de DNS elders wordt gehost — voordat je het naar CloudPress wijst.

Wildcard-certificaten worden niet ondersteund

Een eerdere versie van deze pagina documenteerde een wildcard-parameter en een wildcard-responseveld. Geen van beide bestaat — de API las de parameter nooit en retourneerde het veld nooit. Wildcard-certificaten worden in deze flow bewust niet ondersteund: de hostname moet op de pull zone geregistreerd zijn voordat de challenge wordt uitgegeven, en een *.host-registratie kan niet worden gevalideerd voordat de DNS naar ons wijst. Vraag een certificaat per hostname aan.

Vereist actieve CDN voor de site, anders 409 cdn_not_active. Scope: sites:read voor status; de request-, complete- en refresh-stappen vereisen sites:write en schrijf-/wijzigingsrechten op de site. Die drie stappen proxyen een Bunny-aanroep — een upstream Bunny-fout retourneert 502.

De flow:

  1. POST .../request_certificate retourneert een DNS-01 TXT-challenge die je bij je DNS moet toevoegen.
  2. Voeg het TXT-record toe bij je DNS-provider.
  3. POST .../complete_certificate — Bunny valideert en geeft het certificaat uit.

Certificaatstatus

GET /api/sites/:site_id/domains/:id/certificate

Geretourneerde params
  • provision_type: String | null, http01, dns01_external, of custom
  • challenge: Object | null | het/de toe te voegen DNS-01 TXT-record(s) (terwijl in behandeling)
  • requested_at: Timestamp | null
  • issued_at: Timestamp | null
  • active: Boolean

Certificaat aanvragen (stap 1)

POST /api/sites/:site_id/domains/:id/request_certificate

Neemt geen parameters aan. Retourneert de DNS-01 TXT-challenge die je bij je DNS moet toevoegen.

Certificaat voltooien (stap 2)

POST /api/sites/:site_id/domains/:id/complete_certificate

Roep aan zodra het TXT-record live is; Bunny valideert en geeft het certificaat uit.

Certificaat verversen

POST /api/sites/:site_id/domains/:id/refresh_certificate

Leest de certificaatstatus opnieuw uit bij Bunny en rondt het domein af als er al een certificaat actief is — bijvoorbeeld een dat buiten deze flow om via de standaardflow is uitgegeven — en probeert het voltooien opnieuw als de challenge nog in behandeling is. Er wordt nooit een nieuwe TXT-challenge aangevraagd, dus je kunt dit veilig herhaaldelijk aanroepen terwijl je wacht. Zelfde scope en rechten als de request-/complete-stappen.