Objektien tunnukset

Jokaisella API:n objektilla on id. Tallenna se järjestelmääsi, kun sinun täytyy palata objektiin myöhemmin: nimet ja otsikot voivat muuttua, tunnukset eivät koskaan.

Objekti	`id`	Esimerkki
Kortti, kansio	Merkkijono	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Tapahtuma	Merkkijono, jonka etuliite on `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Lataus	Merkkijono, jonka etuliite on `upl_`	`"upl_8b0c…"`
OAuth-sovellus	Merkkijono, jonka etuliite on `app_`	`"app_5f1c…"`
Kokoelma, käyttäjä, ryhmä, API-avain, webhook, työ ja useimmat muut	Kokonaisluku	`3`

Käsittele tunnuksia läpinäkymättöminä. Älä jäsennä niitä äläkä oleta niiltä mitään muotoa tyypin lisäksi: merkkijonotunnus voi olla mikä tahansa merkkijono, kunhan se on enintään kentän salliman pituinen.

Uudet objektilajit, joihin todennäköisesti viittaat omista järjestelmistäsi, saavat merkkijonotunnukset: lajin nimeävä lyhyt etuliite ja sen perässä 32 heksadesimaalimerkkiä.

Objektien väliset viittaukset

Objektit viittaavat toisiinsa tunnuksilla kentissä, joiden nimi on muotoa <object>_id: collection_id, owner_id, folder_id. Jos haluat liittyvän objektin samaan vastaukseen, käytä expand[]-parametria.

Tunnuksen ottavat polkuparametrit on nimetty samalla tavalla: {card_id}, {webhook_id}, {upload_id}.

Kokoelmat tunnuksella

Kokoelmilla on sekä id että yksilöllinen name, kuten support. Polut, jotka olivat olemassa jo ennen kuin tunnuksista tuli ensisijaisia, ottavat kokoelman nimen:

GET /v1/collections/support/stats

Samat polut ottavat myös tunnuksen muodossa id:<number>:

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

Suosi uudessa koodissa id:-muotoa: ylläpitäjä voi nimetä kokoelman uudelleen, mutta sen tunnus pysyy samana. Pelkistä numeroista koostuva segmentti, kuten /v1/collections/3, tarkoittaa edelleen kokoelmaa, jonka nimi on 3. Kokoelman nimessä ei voi olla merkkiä :, joten nämä kaksi muotoa eivät koskaan sekoitu.

Pyyntöjen rungoissa ja kyselyparametreissa collection_id on aiemman collection-kentän (nimen) rinnalla. Kun annat molemmat, collection_id on etusijalla. Jos collection_id-tunnusta ei ole organisaatiossa tai avain ei saa nähdä kokoelmaa, vastaus on 404 ja koodi collections.not_found.

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

Omat tunnukset

Kortin external_id-kenttään voi tallentaa sen tietueen tunnuksen, josta kortti on peräisin järjestelmässäsi: enintään 512 merkkiä, yksilöllinen organisaation korttien kesken. Sen avulla sinun ei koskaan tarvitse tallentaa kortin Sursa-tunnusta:

Päätepiste	Mitä se tekee
`PUT /v1/cards-by-external-id/{external_id}`	Luo kortin tai korvaa sen sisällön, jos kortti on jo olemassa.
`GET /v1/cards-by-external-id/{external_id}`	Lukee kortin.
`GET /v1/cards?external_id=…`	Etsii kortin listasta muiden suodattimien kanssa.

URL-koodaa external_id, kun se on osa polkua: crm/A-1042 muuttuu muotoon crm%2FA-1042.

Mukautetun lähteen asiakirjoilla on oma external_id oman lähteensä sisällä. Nämä kaksi eivät törmää toisiinsa: mukautetun lähteen korttia muutetaan lähettämällä asiakirja uudelleen sen lähteeseen eikä PUT /v1/cards-by-external-id/… -pyynnöllä, joka vastaa tällöin 409-tilalla ja koodilla cards.managed_by_source.