API-adres en omgevingen
De Sursa API heeft een eigen adres, los van het adres waarmee mensen Sursa in de browser openen. Alle paden beginnen
met /v1.
| Waar Sursa draait | API-adres | Dit portaal |
|---|---|---|
| Sursa-cloud | https://api.sursa.com | https://developers.sursa.com |
| Je eigen installatie | https://api.<your domain>, zoals je beheerder het heeft ingesteld | /developers/ op het API-adres |
| Je installatie zonder apart API-adres | het hoofdadres van de installatie | /developers/ op het hoofdadres |
Het API-adres levert alleen de API: er is geen aanmeldpagina, er zijn geen cookies en er is geen webinterface. Elk request wordt geauthenticeerd met een API-sleutel of een OAuth-toegangstoken. Het adres kan door meerdere servers achter een load balancer worden geleverd; je integratie hoeft niet te weten hoeveel het er zijn.
Integraties die de API op het hoofdadres aanroepen (bijvoorbeeld https://app.sursa.com/v1), blijven werken. Zie
Overstappen naar het API-adres voor de paar verschillen en een overstap in
stappen.
Basis-URL
Bouw elk request op vanuit één basis-URL in je configuratie, zodat dezelfde code in elke omgeving werkt:
export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"
Gebruik alleen HTTPS en houd de sleutel uit de logs van de requests die je verstuurt.
Versie en specificatie
GET /v1/health laat zien of het adres bereikbaar is en geeft de versie van Sursa terug
die het adres levert. Het endpoint antwoordt zonder sleutel, dus je kunt het gebruiken voor monitoring:
curl https://api.sursa.com/v1/health{"ok": true, "version": "v1.4.0"}
Dit is de versie van de release van Sursa, niet van de API. De versie van de API is info.version van de specificatie
ervan. De OpenAPI 3.1-specificatie van de API wordt op hetzelfde adres gepubliceerd, zonder authenticatie:
| Pad | Inhoud |
|---|---|
GET /openapi.json | De openbare specificatie, met dit adres in servers. |
GET /v1/openapi-public.json | Dezelfde specificatie. Ondersteunt ETag en If-None-Match. |
Gebruik hem om een client te genereren, om de API te importeren in een tool zoals Postman of om in de CI te controleren dat je integratie alleen bewerkingen gebruikt van de versie die je verwacht. De API-referentie van dit portaal wordt uit hetzelfde bestand gebouwd.
Testen
Sursa heeft geen aparte testmodus: elk request met een sleutel werkt met de echte gegevens van de organisatie. Zo ontwikkel en test je veilig:
- Maak een aparte sleutel voor ontwikkeling, met de beperktste rol en scopes die het werk nodig heeft.
- Schrijf naar een aparte collectie, bijvoorbeeld
sandbox, die alleen je team kan zien, en verwijder die als je klaar bent. - Heeft je bedrijf een aparte organisatie of installatie van Sursa om te testen, laat de basis-URL en de sleutel dan daarnaar wijzen. Verder verandert er niets in je code.
- Maak nieuwe pogingen vanaf het begin veilig: stuur bij elke
POSTenPATCHeen Idempotency-Key mee.
De console Uitproberen op elke endpointpagina van de API-referentie verstuurt echte requests met een sleutel die je erin plakt. De sleutel blijft in het geheugen van het tabblad van de browser en wordt alleen naar het API-adres gestuurd.
Netwerkvereisten
- Uitgaand HTTPS-verkeer (poort 443) van je servers naar het API-adres.
- Sta in firewallregels de hostnaam toe in plaats van vaste IP-adressen, waar je netwerk dat toelaat: de servers achter het adres kunnen veranderen als er capaciteit bij komt.
- Browserapplicaties kunnen de API rechtstreeks aanroepen: responses staan elke origin toe
(
Access-Control-Allow-Origin: *), zonder cookies. Houd er rekening mee dat een sleutel die in een browser wordt gebruikt, zichtbaar is voor de gebruiker van die browser.