API-viite

NexBasiran julkinen API on REST + JSON, versioitu polun /api/v1/public/* alla. Jokainen päätepiste tunnistautuu cvp_pub:cvp_sec-tunnisteparillasi, on scope-rajattu ja kursorisivutettu silloin kun se palauttaa listan.

Perus-URL

https://app.nexbasira.com/api/v1/public

Itse isännöidyissä asennuksissa vaihda isäntä omaasi. Polku on sama.

Osiot

• Tunnistautuminen — tunnistepari, allekirjoitusskeema, scope-luettelo
• Sivutus + idempotenssi — kursorisivutus + Idempotency-Key-otsake
• Virheet + nopeusrajat — virhekuoren muoto, X-RateLimit-*-otsakkeet
• Istunnot — luo, listaa, hae, päätä, kutsu
• Todisteet — listaa, hae, allekirjoitettu lataus-URL
• Valkotaulut — listaa istunnoittain
• Webhook-päätepisteet — rekisteröi / kierrätä-salaisuus / testilaukaus
• Brändäys — vain luku julkisessa API:ssa; muutokset SPA:n kautta
• Organisaatio — vain luku -organisaatiometadata

OpenAPI-skeema

Suodatettu OpenAPI 3.1 -spesifikaatio (vain public-api-tagatut operaatiot) tarjoillaan osoitteessa https://app.nexbasira.com/api/public-schema/. Käytä sitä suoraan koodigeneraattoreiden kanssa:

# Node typed types
npx openapi-typescript https://app.nexbasira.com/api/public-schema/ -o src/nb-types.ts

# Python typed models
datamodel-codegen \
  --url https://app.nexbasira.com/api/public-schema/ \
  --input-file-type openapi \
  --output-model-type pydantic_v2.BaseModel \
  --output cvp_models.py

SDK:mme (@nexbasira/node + nexbasira Pythonille) on rakennettu näiden generoitujen tyyppien päälle ja lisää käsin kirjoitettua ergonomiaa — tyypitetyt virheet, async-iteraattorisivutus, webhook-varmennusapurit.

API:n vakaus

Julkinen API noudattaa semver-URL-nimiavaruus-mallia. Rikkovat muutokset toimitetaan uuden etuliitteen alla (/api/v2/public/*), ja edellinen versio on käytössä vielä vähintään 12 kuukautta ennen poistoa. Additiiviset muutokset (uudet valinnaiset kentät, uudet päätepisteet, uudet tapahtumatyypit) toimitetaan paikallaan; SDK:t kohtelevat tuntemattomia kenttiä eteenpäin yhteensopivina.