Objekt-id’er

Alle objekter i API’et har et id. Gem det i dit system, når du skal tilbage til objektet: Navne og titler kan ændre sig, id’er gør aldrig.

Objekt	`id`	Eksempel
Kort, mappe	Streng	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Hændelse	Streng med præfikset `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Upload	Streng med præfikset `upl_`	`"upl_8b0c…"`
OAuth-app	Streng med præfikset `app_`	`"app_5f1c…"`
Samling, bruger, gruppe, API-nøgle, webhook, job og de fleste andre	Heltal	`3`

Behandl id’er som uigennemsigtige. Fortolk dem ikke, og antag ikke noget format ud over typen: Et streng-id kan være en hvilken som helst streng op til den længde, som feltet tillader.

Nye slags objekter, som du sandsynligvis vil henvise til fra dine egne systemer, får streng-id’er med et kort præfiks, der angiver slagsen, efterfulgt af 32 hexadecimale tegn.

Henvisninger mellem objekter

Objekter henviser til hinanden med id i felter med navnet <object>_id: collection_id, owner_id, folder_id. Brug expand[] for at få det relaterede objekt med i samme svar.

Stiparametre, der tager et id, navngives på samme måde: {card_id}, {webhook_id}, {upload_id}.

Samlinger efter id

Samlinger har både et id og et unikt name, fx support. Stier, der fandtes, før id’er blev den foretrukne form, tager samlingens navn:

GET /v1/collections/support/stats

De samme stier tager også id’et, skrevet som id:<number>:

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

Foretræk formen id: i ny kode: En administrator kan omdøbe en samling, men dens id forbliver det samme. Et segment med kun cifre, fx /v1/collections/3, betyder stadig samlingen med navnet 3. Et samlingsnavn kan ikke indeholde :, så de to former blandes aldrig sammen.

I brødteksten i anmodninger og i forespørgselsparametre står collection_id ved siden af det tidligere collection (navnet). Sender du begge, vinder collection_id. Et collection_id, der ikke findes i organisationen, eller som nøglen ikke har lov til at se, returnerer 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"

Dine egne id’er

Kort kan have id’et på den post, de kommer fra i dit system, i external_id: op til 512 tegn, unikt blandt organisationens kort. Så behøver du aldrig gemme kortets id i Sursa:

Operation	Hvad den gør
`PUT /v1/cards-by-external-id/{external_id}`	Opretter kortet eller erstatter dets indhold, hvis det findes.
`GET /v1/cards-by-external-id/{external_id}`	Læser kortet.
`GET /v1/cards?external_id=…`	Finder kortet i en liste sammen med andre filtre.

URL-kod external_id, når det er en del af stien: crm/A-1042 bliver til crm%2FA-1042.

Dokumenter i en brugerdefineret kilde har deres eget external_id inden for kilden. De to kolliderer ikke: Et kort fra en brugerdefineret kilde ændres ved at sende dokumentet til kilden igen, ikke med PUT /v1/cards-by-external-id/…, som i så fald svarer 409 med koden cards.managed_by_source.