Objektide ID-d

Igal API objektil on id. Salvestage see oma süsteemi, kui peate objekti juurde hiljem tagasi tulema: nimed ja pealkirjad võivad muutuda, ID-d mitte kunagi.

Objekt	`id`	Näide
Kaart, kaust	String	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Sündmus	String eesliitega `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Üleslaadimine	String eesliitega `upl_`	`"upl_8b0c…"`
OAuth-rakendus	String eesliitega `app_`	`"app_5f1c…"`
Kogu, kasutaja, rühm, API-võti, veebihaak, töö ja enamik teisi	Täisarv	`3`

Käsitlege ID-sid läbipaistmatutena. Ärge neid parsige ega eeldage peale tüübi mingit vormingut: string-ID võib olla mis tahes string kuni pikkuseni, mida selle väli lubab.

Uued objektiliigid, millele te tõenäoliselt oma süsteemidest viitate, saavad string-ID-d: liiki nimetav lühike eesliide, millele järgneb 32 kuueteistkümnendsüsteemi märki.

Objektidevahelised viited

Objektid viitavad üksteisele ID kaudu väljadel, mille nimi on kujul <object>_id: collection_id, owner_id, folder_id. Seotud objekti saamiseks samas vastuses kasutage parameetrit expand[].

ID-d vastu võtvad teeparameetrid on nimetatud samamoodi: {card_id}, {webhook_id}, {upload_id}.

Kogud ID järgi

Kogudel on nii id kui ka unikaalne name, näiteks support. Teed, mis olid olemas enne, kui hakati eelistama ID-sid, võtavad vastu kogu nime:

GET /v1/collections/support/stats

Samad teed võtavad vastu ka ID, mis kirjutatakse kujul id:<number>:

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

Eelistage uues koodis kuju id:: administraator võib kogu ümber nimetada, kuid selle ID jääb samaks. Ainult numbritest koosnev segment, näiteks /v1/collections/3, tähendab endiselt kogu, mille nimi on 3. Kogu nimi ei saa sisaldada märki :, seega ei lähe need kaks kuju kunagi segi.

Päringu kehades ja päringuparameetrites on collection_id varasema välja collection (nimi) kõrval. Kui edastate mõlemad, kehtib collection_id. Väli collection_id, mille väärtust organisatsioonis ei ole või mida võtmel ei ole lubatud näha, tagastab 404 koodiga collections.not_found.

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

Teie oma ID-d

Kaardid võivad väljal external_id kanda selle kirje ID-d teie süsteemis, kust kaart pärineb: kuni 512 märki, unikaalne organisatsiooni kaartide seas. Selle abil ei pea te kunagi kaardi Sursa ID-d salvestama:

Lõpp-punkt	Mida see teeb
`PUT /v1/cards-by-external-id/{external_id}`	Loob kaardi või asendab selle sisu, kui kaart on olemas.
`GET /v1/cards-by-external-id/{external_id}`	Loeb kaardi.
`GET /v1/cards?external_id=…`	Leiab kaardi loendist koos teiste filtritega.

URL-kodeerige external_id, kui see on tee osa: crm/A-1042 muutub kujuks crm%2FA-1042.

Kohandatud allika dokumentidel on oma allika piires oma external_id. Need kaks ei põrku: kohandatud allika kaarti muudetakse dokumendi uuesti saatmisega selle allikasse, mitte päringuga PUT /v1/cards-by-external-id/…, mis vastab sel juhul 409 koodiga cards.managed_by_source.