ID’s van objecten

Elk object van de API heeft een id. Sla die op in je systeem als je later naar het object terug moet: namen en titels kunnen veranderen, ID’s nooit.

Object	`id`	Voorbeeld
Kaart, map	String	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Event	String met het voorvoegsel `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Upload	String met het voorvoegsel `upl_`	`"upl_8b0c…"`
OAuth-app	String met het voorvoegsel `app_`	`"app_5f1c…"`
Collectie, gebruiker, groep, API-sleutel, webhook, job en de meeste andere	Geheel getal	`3`

Behandel ID’s als ondoorzichtig. Parseer ze niet en ga niet uit van een vorm buiten het type: een string-ID kan elke string zijn, tot de lengte die het veld toestaat.

Nieuwe soorten objecten waarnaar je waarschijnlijk vanuit je eigen systemen verwijst, krijgen string-ID’s met een kort voorvoegsel dat de soort aangeeft, gevolgd door 32 hexadecimale tekens.

Verwijzingen tussen objecten

Objecten verwijzen naar elkaar met een ID, in velden met de naam <object>_id: collection_id, owner_id, folder_id. Om het gerelateerde object in dezelfde response te krijgen, gebruik je expand[].

Padparameters die een ID aannemen, heten op dezelfde manier: {card_id}, {webhook_id}, {upload_id}.

Collecties op ID

Collecties hebben zowel een id als een unieke name, zoals support. Paden die al bestonden voordat ID’s de voorkeur kregen, nemen de naam van de collectie aan:

GET /v1/collections/support/stats

Dezelfde paden nemen ook de ID aan, geschreven als id:<number>:

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

Gebruik in nieuwe code bij voorkeur de vorm id:: een beheerder kan een collectie een andere naam geven, maar de ID blijft hetzelfde. Een segment van alleen cijfers, zoals /v1/collections/3, betekent nog steeds de collectie met de naam 3. De naam van een collectie kan geen : bevatten, dus de twee vormen raken nooit door elkaar.

In request-bodies en queryparameters staat collection_id naast het eerdere collection (de naam). Geef je ze allebei mee, dan gaat collection_id voor. Een collection_id die niet bestaat in de organisatie of die de sleutel niet mag zien, geeft 404 met de code collections.not_found.

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

Eigen ID’s

Kaarten kunnen in external_id de ID dragen van het record in je systeem waar ze vandaan komen: maximaal 512 tekens, uniek onder de kaarten van de organisatie. Daarmee hoef je de Sursa-ID van een kaart nooit op te slaan:

Endpoint	Wat het doet
`PUT /v1/cards-by-external-id/{external_id}`	Maakt de kaart, of vervangt de inhoud ervan als hij al bestaat.
`GET /v1/cards-by-external-id/{external_id}`	Leest de kaart.
`GET /v1/cards?external_id=…`	Vindt de kaart in een lijst, met andere filters.

Codeer de external_id voor de URL als hij deel uitmaakt van het pad: crm/A-1042 wordt crm%2FA-1042.

Documenten van een eigen bron hebben hun eigen external_id binnen hun bron. De twee zitten elkaar niet in de weg: een kaart van een eigen bron wijzig je door het document opnieuw naar de bron te sturen, niet met PUT /v1/cards-by-external-id/…, dat in dat geval antwoordt met 409 en de code cards.managed_by_source.