Identifikatori objekata

Svaki objekt API-ja ima id. Pohranite ga u svojem sustavu kad se trebate vratiti objektu: imena i naslovi mogu se promijeniti, ID-ovi nikada.

Objekt	`id`	Primjer
Kartica, mapa	Niz znakova	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Događaj	Niz znakova s prefiksom `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Učitavanje	Niz znakova s prefiksom `upl_`	`"upl_8b0c…"`
OAuth aplikacija	Niz znakova s prefiksom `app_`	`"app_5f1c…"`
Zbirka, korisnik, grupa, API ključ, webhook, posao i većina ostalih	Cijeli broj	`3`

Identifikatore smatrajte neprozirnima. Ne raščlanjujte ih i ne pretpostavljajte nikakav format osim tipa: ID u obliku niza znakova može biti bilo koji niz, do duljine koju njegovo polje dopušta.

Nove vrste objekata na koje ćete vjerojatno upućivati iz vlastitih sustava dobivaju identifikatore u obliku niza znakova s kratkim prefiksom koji imenuje vrstu, nakon kojeg slijede 32 heksadekadska znaka.

Upućivanja između objekata

Objekti upućuju jedni na druge putem ID-a, u poljima s imenom <object>_id: collection_id, owner_id, folder_id. Da biste povezani objekt dobili u istom odgovoru, koristite expand[].

Parametri putanje koji primaju ID imenuju se na isti način: {card_id}, {webhook_id}, {upload_id}.

Zbirke prema ID-u

Zbirke imaju i id i jedinstveno ime name, kao što je support. Putanje koje su postojale prije nego što su ID-ovi postali preporučeni primaju ime zbirke:

GET /v1/collections/support/stats

Iste putanje primaju i ID, zapisan kao id:<number>:

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

U novom kodu prednost dajte obliku id:: administrator može preimenovati zbirku, ali njezin ID ostaje isti. Segment koji se sastoji samo od znamenki, kao što je /v1/collections/3, i dalje znači zbirku s imenom 3. Ime zbirke ne može sadržavati :, pa se ta dva oblika nikada ne miješaju.

U tijelima zahtjeva i parametrima upita collection_id stoji uz raniji collection (ime). Kad proslijedite oba, prednost ima collection_id. collection_id koji ne postoji u organizaciji ili koji ključ ne smije vidjeti vraća 404 s kodom collections.not_found.

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

Vlastiti identifikatori

Kartice mogu nositi ID zapisa iz vašeg sustava iz kojeg potječu, u polju external_id: do 512 znakova, jedinstven među karticama organizacije. Uz njega nikada ne morate pohranjivati ID kartice u Sursi:

Operacija	Što radi
`PUT /v1/cards-by-external-id/{external_id}`	Stvara karticu ili zamjenjuje njezin sadržaj ako postoji.
`GET /v1/cards-by-external-id/{external_id}`	Čita karticu.
`GET /v1/cards?external_id=…`	Pronalazi karticu u popisu, uz druge filtre.

Kodirajte external_id za URL kad je dio putanje: crm/A-1042 postaje crm%2FA-1042.

Dokumenti vlastitog izvora imaju vlastiti external_id unutar svojeg izvora. Ta se dva identifikatora ne sukobljavaju: kartica vlastitog izvora mijenja se ponovnim slanjem dokumenta njegovu izvoru, a ne pomoću PUT /v1/cards-by-external-id/…, koji u tom slučaju odgovara s 409 i kodom cards.managed_by_source.