ID dels objectes

Cada objecte de l’API té un id. Deseu-lo al vostre sistema quan hàgiu de tornar a l’objecte: els noms i els títols poden canviar, els ID no canvien mai.

Objecte	`id`	Exemple
Entrada, carpeta	Cadena	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Esdeveniment	Cadena amb el prefix `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Pujada	Cadena amb el prefix `upl_`	`"upl_8b0c…"`
Aplicació OAuth	Cadena amb el prefix `app_`	`"app_5f1c…"`
Col·lecció, usuari, grup, clau d’API, webhook, treball i la majoria dels altres	Enter	`3`

Tracteu els ID com a opacs. No els analitzeu ni suposeu cap format més enllà del tipus: un ID de cadena pot ser qualsevol cadena, fins a la longitud que permeti el seu camp.

Els tipus d’objecte nous als quals és probable que feu referència des dels vostres sistemes reben ID de cadena amb un prefix curt que indica el tipus, seguit de 32 caràcters hexadecimals.

Referències entre objectes

Els objectes es fan referència entre si per ID, en camps amb el nom <object>_id: collection_id, owner_id, folder_id. Per obtenir l’objecte relacionat a la mateixa resposta, feu servir expand[].

Els paràmetres de camí que reben un ID segueixen la mateixa pauta: {card_id}, {webhook_id}, {upload_id}.

Col·leccions per ID

Les col·leccions tenen alhora un id i un name únic, com ara support. Els camins que existien abans que es donés preferència als ID reben el nom de la col·lecció:

GET /v1/collections/support/stats

Els mateixos camins també accepten l’ID, escrit com a id:<number>:

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

Al codi nou, feu servir preferentment la forma id:: qui administra l’organització pot canviar el nom d’una col·lecció, però el seu ID es manté. Un segment format només per xifres, com ara /v1/collections/3, continua volent dir la col·lecció amb el nom 3. El nom d’una col·lecció no pot contenir :, de manera que les dues formes no es confonen mai.

Als cossos de les sol·licituds i als paràmetres de consulta, collection_id conviu amb l’anterior collection (el nom). Si passeu tots dos, preval collection_id. Un collection_id que no existeix a l’organització, o que la clau no pot veure, retorna 404 amb el codi collections.not_found.

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

Els vostres propis ID

Les entrades poden portar a external_id l’ID de l’element del vostre sistema del qual provenen: fins a 512 caràcters, únic entre les entrades de l’organització. Amb aquest camp no cal desar mai l’ID de Sursa d’una entrada:

Punt final	Què fa
`PUT /v1/cards-by-external-id/{external_id}`	Crea l’entrada o, si ja existeix, en substitueix el contingut.
`GET /v1/cards-by-external-id/{external_id}`	Llegeix l’entrada.
`GET /v1/cards?external_id=…`	Troba l’entrada en una llista, amb altres filtres.

Codifiqueu per a URL l’external_id quan formi part del camí: crm/A-1042 es converteix en crm%2FA-1042.

Els documents d’una font personalitzada tenen el seu propi external_id dins de la seva font. Els dos no entren en conflicte: una entrada d’una font personalitzada es canvia tornant a enviar el document a la seva font, no amb PUT /v1/cards-by-external-id/…, que en aquest cas respon 409 amb el codi cards.managed_by_source.