Preskoči na sadržaj
Sursa Developers

Prijelaz na adresu API-ja

Ranije integracije pozivaju API na glavnoj adresi Surse, onoj koju ljudi otvaraju u pregledniku, na primjer https://app.sursa.com/v1/…. API sada ima i vlastitu adresu, https://api.sursa.com u oblaku ili https://api.<your domain> u vašoj instalaciji. Namijenjena je integracijama: skalira se horizontalno iza uravnoteživača opterećenja i ne poslužuje ništa osim API-ja.

Prijelaz nije obavezan. Glavna adresa i dalje poslužuje /v1 za postojeće integracije, bez datuma završetka i bez preusmjeravanja. Prijeđite kad vam odgovara, kako biste dobili prednosti adrese API-ja, i koristite je za svaku novu integraciju.

Što ostaje isto

  • Putanje, parametri, polja, kodovi pogrešaka i događaji: GET /v1/cards isti je zahtjev na obje adrese.
  • API ključevi. Isti ključevi kb_ i kbsrc_ rade na obje adrese, s istom ulogom, opsezima i podatkovnim profilom.
  • Ključevi idempotentnosti, ograničenja učestalosti i kvote. Zahtjevi na obje adrese ubrajaju se u iste kvote organizacije.
  • Webhookovi. Isporuke, potpisi i tajne ne ovise o adresi koju pozivate.
  • Poveznice u odgovorima. doc_url pogreške vodi na ovaj portal, a zaglavlje Link stranice popisa vodi na adresu API-ja, koju god adresu pozivate.

Što je drukčije na adresi API-ja

Na glavnoj adresiNa adresi API-ja
Sve operacije web-aplikacije, uključujući interneSamo operacije iz javne reference API-ja. Svaka druga putanja odgovara s 404 i kodom api.not_found.
Ključ u X-API-Key ili Authorization ili kolačić sesije preglednikaKljuč ili OAuth pristupni token, po mogućnosti u Authorization: Bearer. Kolačići se zanemaruju.
GET /auth/meGET /v1/me. Putanje unutar /auth/ ne poslužuju se.
Način „View as” (prikaz iz perspektive drugog korisnika) putem kolačićaZaglavlje X-View-As, za ključeve s ulogom admin.
Jedan poslužitelj ili nepromjenjiv skupViše poslužitelja iza uravnoteživača opterećenja.

Posljednji je redak važan samo u jednom slučaju: za odgovor koji POST /v1/chat šalje kao tok. Prekinuti tok nastavlja se od Last-Event-ID samo na poslužitelju koji piše odgovor. Ako vaša integracija nastavlja tokove, svakom pitanju dodijelite request_id, kako bi ponovni pokušaj na drugom poslužitelju dobio spremljeni odgovor umjesto drugog odgovora. V. Nastavak prekinutog toka.

Prije prijelaza

Provjerite je li svaki poziv javan. Popišite putanje koje vaša integracija poziva i potražite svaku u referenci API-ja ili ih usporedite sa specifikacijom nove adrese:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Putanja koja nedostaje u javnoj referenci pripada web-aplikaciji. Na glavnoj adresi i dalje radi, ali se na adresi API-ja ne poslužuje, a njezin oblik nije javna obveza. Zamijenite je javnom operacijom ili taj dio integracije zadržite na glavnoj adresi i javite svojoj kontaktnoj osobi u Sursi što vam treba.

Provjerite kako se autentificirate. Ako se integracija prijavljuje lozinkom korisnika i kolačićem sesije, najprije je prebacite na API ključ. Ako šalje X-API-Key, prelazak na Authorization: Bearer preporučuje se, ali nije obavezan.

Provjerite svoju mrežu. U vatrozidu i proxyjima dopustite odlazni HTTPS prema novom nazivu hosta.

Prijelaz korak po korak

  1. Pretvorite osnovni URL u postavku svoje integracije, ako to već nije.

  2. Isprobajte novu adresu zahtjevom za čitanje:

    curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

  3. Pokrenite skup testova svoje integracije na novoj adresi, s testnim ključem i testnom zbirkom.

  4. Prebacite dio prometa, na primjer jedan radni proces ili jedno okruženje, i u zapisnicima pratite 404 api.not_found, 401 i 5xx. Svaki odgovor nosi X-Request-Id; čuvajte ga uz svoje zapisnike.

  5. Prebacite ostatak. Stari osnovni URL zadržite neko vrijeme u konfiguraciji kako biste se mogli vratiti u nekoliko sekundi.

Što provjeriti nakon prijelaza

  • GET /v1/health na novoj adresi vraća istu version kao i na staroj.
  • Odgovori sadrže zaglavlja RateLimit. Ako vaša integracija sama usporava prema X-RateLimit-*, može to i dalje činiti: šalju se oba skupa. V. Ograničenja učestalosti i kvote.
  • Ako vaša integracija radi u pregledniku, više joj ne treba vlastiti proxy za CORS: adresa API-ja dopušta zahtjeve s bilo kojeg origina, bez kolačića.