Идентификатори на обектите

Всеки обект в API има id. Съхранявайте го в системата си, когато трябва да се върнете към обекта: имената и заглавията може да се променят, идентификаторите – никога.

Обект	`id`	Пример
Карта, папка	Низ	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Събитие	Низ с префикс `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Качване	Низ с префикс `upl_`	`"upl_8b0c…"`
OAuth приложение	Низ с префикс `app_`	`"app_5f1c…"`
Колекция, потребител, група, API ключ, уебхук, задание и повечето други	Цяло число	`3`

Третирайте идентификаторите като непрозрачни. Не ги анализирайте и не предполагайте формат отвъд типа: идентификатор от тип низ може да бъде всеки низ с дължина до разрешената за полето му.

Новите видове обекти, към които вероятно ще сочите от собствените си системи, получават идентификатори от тип низ с кратък префикс, който назовава вида, последван от 32 шестнайсетични знака.

Препратки между обектите

Обектите сочат един към друг чрез ID в полета с имена <object>_id: collection_id, owner_id, folder_id. За да получите свързания обект в същия отговор, използвайте expand[].

Параметрите на пътя, които приемат ID, се наричат по същия начин: {card_id}, {webhook_id}, {upload_id}.

Колекции по ID

Колекциите имат и id, и уникално име name, например support. Пътищата, които са съществували, преди идентификаторите да станат предпочитани, приемат името на колекцията:

GET /v1/collections/support/stats

Същите пътища приемат и ID, записано като id:<number>:

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

В новия код предпочитайте записа id:: администраторът може да преименува колекцията, но нейното ID остава същото. Сегмент само от цифри, например /v1/collections/3, продължава да означава колекцията с име 3. Името на колекция не може да съдържа :, затова двата записа никога не се объркват.

В телата на заявките и в параметрите на заявката collection_id стои до по-ранното collection (името). Когато подадете и двете, предимство има collection_id. collection_id, което не съществува в организацията или което ключът няма право да вижда, връща 404 с кода collections.not_found.

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

Собствени идентификатори

Картите може да носят в external_id идентификатора на записа във вашата система, от който идват: до 512 знака, уникален сред картите на организацията. С него никога не се налага да съхранявате идентификатора на картата в Sursa:

Операция	Какво прави
`PUT /v1/cards-by-external-id/{external_id}`	Създава картата или заменя съдържанието ѝ, ако тя съществува.
`GET /v1/cards-by-external-id/{external_id}`	Чете картата.
`GET /v1/cards?external_id=…`	Намира картата в списък, заедно с други филтри.

Кодирайте external_id за URL, когато е част от пътя: crm/A-1042 става crm%2FA-1042.

Документите на собствен източник имат собствен external_id в рамките на своя източник. Двата не си пречат: карта от собствен източник се променя, като документът се изпрати отново до неговия източник, а не с PUT /v1/cards-by-external-id/…, който в такъв случай отговаря с 409 и кода cards.managed_by_source.