Objektens id

Varje objekt i API:et har ett id. Spara det i ditt system när du behöver komma tillbaka till objektet: namn och rubriker kan ändras, id aldrig.

Objekt	`id`	Exempel
Kort, mapp	Sträng	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Händelse	Sträng med prefixet `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Uppladdning	Sträng med prefixet `upl_`	`"upl_8b0c…"`
OAuth-app	Sträng med prefixet `app_`	`"app_5f1c…"`
Samling, användare, grupp, API-nyckel, webhook, jobb och de flesta andra	Heltal	`3`

Behandla id som ogenomskinliga. Tolka dem inte och anta inget format utöver typen: ett id av typen sträng kan vara vilken sträng som helst, upp till den längd som fältet tillåter.

Nya typer av objekt som du sannolikt kommer att hänvisa till från dina egna system får id av typen sträng med ett kort prefix som anger typen, följt av 32 hexadecimala tecken.

Referenser mellan objekt

Objekt hänvisar till varandra med id, i fält som heter <object>_id: collection_id, owner_id, folder_id. För att få det relaterade objektet i samma svar använder du expand[].

Sökvägsparametrar som tar ett id namnges på samma sätt: {card_id}, {webhook_id}, {upload_id}.

Samlingar med id

Samlingar har både ett id och ett unikt namn (name), till exempel support. Sökvägar som fanns innan id blev det föredragna sättet tar samlingens namn:

GET /v1/collections/support/stats

Samma sökvägar tar också id:t, skrivet som id:<number>:

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

Använd hellre formen id: i ny kod: en administratör kan byta namn på en samling, men dess id förblir detsamma. Ett segment med bara siffror, till exempel /v1/collections/3, betyder fortfarande samlingen som heter 3. Ett samlingsnamn kan inte innehålla :, så de två formerna blandas aldrig ihop.

I anropens brödtext och i frågeparametrar står collection_id bredvid det tidigare collection (namnet). När du skickar båda gäller collection_id. Ett collection_id som inte finns i organisationen, eller som nyckeln inte får se, returnerar 404 med koden collections.not_found.

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

Egna id:n

Kort kan bära id:t för den post i ditt system som de kommer från, i external_id: upp till 512 tecken, unikt bland organisationens kort. Med det behöver du aldrig spara ett korts id i Sursa:

Slutpunkt	Vad den gör
`PUT /v1/cards-by-external-id/{external_id}`	Skapar kortet, eller ersätter dess innehåll om det finns.
`GET /v1/cards-by-external-id/{external_id}`	Läser kortet.
`GET /v1/cards?external_id=…`	Hittar kortet i en lista, tillsammans med andra filter.

URL-koda external_id när det ingår i sökvägen: crm/A-1042 blir crm%2FA-1042.

Dokument i en egen källa har ett eget external_id inom sin källa. De två krockar inte: ett kort i en egen källa ändras genom att du skickar dokumentet till källan igen, inte med PUT /v1/cards-by-external-id/…, som i så fall svarar 409 med koden cards.managed_by_source.