Objektenes ID-er

Alle objekter i API-et har en id. Lagre den i systemet ditt når du trenger å komme tilbake til objektet: Navn og titler kan endres, ID-er gjør det aldri.

Objekt	`id`	Eksempel
Kort, mappe	Streng	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Hendelse	Streng med prefikset `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Opplasting	Streng med prefikset `upl_`	`"upl_8b0c…"`
OAuth-applikasjon	Streng med prefikset `app_`	`"app_5f1c…"`
Samling, bruker, gruppe, API-nøkkel, webhook, jobb og de fleste andre	Heltall	`3`

Behandle ID-er som ugjennomsiktige. Ikke tolk dem, og ikke anta noe format utover typen: En streng-ID kan være en hvilken som helst streng, opptil den lengden feltet tillater.

Nye objekttyper som du sannsynligvis kommer til å vise til fra dine egne systemer, får streng-ID-er med et kort prefiks som angir typen, etterfulgt av 32 heksadesimale tegn.

Referanser mellom objekter

Objekter viser til hverandre med ID, i felt som heter <object>_id: collection_id, owner_id, folder_id. For å få det relaterte objektet i samme svar bruker du expand[].

Baneparametere som tar en ID, har navn etter samme mønster: {card_id}, {webhook_id}, {upload_id}.

Samlinger med ID

Samlinger har både en id og et unikt name, for eksempel support. Baner som fantes før ID-er ble foretrukket, tar navnet på samlingen:

GET /v1/collections/support/stats

De samme banene tar også ID-en, skrevet som id:<number>:

curl https://api.sursa.com/v1/collections/id:3/stats \
  -H "Authorization: Bearer $SURSA_API_KEY"

Foretrekk formen id: i ny kode: En administrator kan gi en samling nytt navn, men ID-en forblir den samme. Et segment med bare sifre, for eksempel /v1/collections/3, betyr fortsatt samlingen som heter 3. Et samlingsnavn kan ikke inneholde :, så de to formene blandes aldri sammen.

I forespørselens brødtekst og i spørringsparametere står collection_id ved siden av det tidligere collection (navnet). Når du sender begge, gjelder collection_id. En collection_id som ikke finnes i organisasjonen, eller som nøkkelen ikke har lov til å se, returnerer 404 med koden collections.not_found.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "collection_id=3"

Dine egne ID-er

Kort kan ha ID-en til posten de kommer fra i systemet ditt, i external_id: opptil 512 tegn, unik blant organisasjonens kort. Da trenger du aldri å lagre Sursa-ID-en til et kort:

Operasjon	Hva den gjør
`PUT /v1/cards-by-external-id/{external_id}`	Oppretter kortet, eller erstatter innholdet hvis kortet finnes.
`GET /v1/cards-by-external-id/{external_id}`	Leser kortet.
`GET /v1/cards?external_id=…`	Finner kortet i en liste, sammen med andre filtre.

URL-kod external_id når den er en del av banen: crm/A-1042 blir crm%2FA-1042.

Dokumenter i en egendefinert kilde har sin egen external_id innenfor kilden. De to kolliderer ikke: Et kort fra en egendefinert kilde endres ved at du sender dokumentet til kilden på nytt, ikke med PUT /v1/cards-by-external-id/…, som i så fall svarer 409 med koden cards.managed_by_source.