Identifikátory objektov

Každý objekt API má id. Uložte si ho vo svojom systéme, keď sa potrebujete k objektu vrátiť: názvy sa môžu meniť, identifikátory nikdy.

Objekt	`id`	Príklad
Karta, priečinok	Reťazec	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Udalosť	Reťazec s predponou `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Nahrávanie	Reťazec s predponou `upl_`	`"upl_8b0c…"`
Aplikácia OAuth	Reťazec s predponou `app_`	`"app_5f1c…"`
Kolekcia, používateľ, skupina, kľúč API, webhook, úloha a väčšina ostatných	Celé číslo	`3`

Identifikátory považujte za nepriehľadné. Neanalyzujte ich a nepredpokladajte iný formát než typ: reťazcový identifikátor môže byť ľubovoľný reťazec až do dĺžky, ktorú jeho pole povoľuje.

Nové druhy objektov, na ktoré budete pravdepodobne odkazovať zo svojich systémov, dostanú reťazcové identifikátory s krátkou predponou, ktorá pomenúva druh, a za ňou 32 šestnástkových znakov.

Odkazy medzi objektmi

Objekty na seba odkazujú cez ID v poliach s názvom <object>_id: collection_id, owner_id, folder_id. Ak chcete súvisiaci objekt dostať v tej istej odpovedi, použite expand[].

Parametre cesty, ktoré prijímajú ID, sa pomenúvajú rovnako: {card_id}, {webhook_id}, {upload_id}.

Kolekcie podľa ID

Kolekcie majú id aj jedinečný názov name, napríklad support. Cesty, ktoré existovali predtým, ako sa začali uprednostňovať identifikátory, prijímajú názov kolekcie:

GET /v1/collections/support/stats

Tie isté cesty prijímajú aj ID zapísané ako id:<number>:

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

V novom kóde uprednostnite tvar id:: administrátor môže kolekciu premenovať, ale jej ID zostane rovnaké. Segment zložený len z číslic, napríklad /v1/collections/3, stále znamená kolekciu s názvom 3. Názov kolekcie nemôže obsahovať :, takže sa tieto dva tvary nikdy nezamenia.

V telách požiadaviek a parametroch dotazu stojí collection_id vedľa staršieho collection (názov). Keď odošlete oba, platí collection_id. collection_id, ktoré v organizácii neexistuje alebo ktoré kľúč nesmie vidieť, vráti 404 s kódom collections.not_found.

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

Vlastné identifikátory

Karty môžu v external_id niesť identifikátor záznamu, z ktorého vo vašom systéme pochádzajú: najviac 512 znakov, jedinečný medzi kartami organizácie. Vďaka nemu nikdy nemusíte ukladať ID karty v Surse:

Operácia	Čo robí
`PUT /v1/cards-by-external-id/{external_id}`	Vytvorí kartu, alebo nahradí jej obsah, ak existuje.
`GET /v1/cards-by-external-id/{external_id}`	Načíta kartu.
`GET /v1/cards?external_id=…`	Nájde kartu v zozname spolu s ďalšími filtrami.

Keď je external_id súčasťou cesty, zakódujte ho pre URL: z crm/A-1042 sa stane crm%2FA-1042.

Dokumenty vlastného zdroja majú vlastné external_id v rámci svojho zdroja. Tieto dva identifikátory sa nezrazia: kartu vlastného zdroja zmeníte opätovným odoslaním dokumentu do jej zdroja, nie cez PUT /v1/cards-by-external-id/…, ktoré v takom prípade odpovie 409 s kódom cards.managed_by_source.