Objekt-IDs

Jedes Objekt der API hat eine id. Speichern Sie sie in Ihrem System, wenn Sie später auf das Objekt zurückkommen müssen: Namen und Titel können sich ändern, IDs nie.

Objekt	`id`	Beispiel
Karte, Ordner	Zeichenkette	`"3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"`
Ereignis	Zeichenkette mit dem Präfix `evt_`	`"evt_0123456789abcdef0123456789abcdef"`
Upload	Zeichenkette mit dem Präfix `upl_`	`"upl_8b0c…"`
OAuth-Anwendung	Zeichenkette mit dem Präfix `app_`	`"app_5f1c…"`
Sammlung, Benutzer, Gruppe, API-Schlüssel, Webhook, Job und die meisten anderen	Ganze Zahl	`3`

Behandeln Sie IDs als undurchsichtig. Zerlegen Sie sie nicht und nehmen Sie kein Format über den Typ hinaus an: Eine Zeichenketten-ID kann jede Zeichenkette sein, bis zu der Länge, die ihr Feld erlaubt.

Neue Arten von Objekten, auf die Sie wahrscheinlich aus Ihren eigenen Systemen verweisen werden, erhalten Zeichenketten-IDs mit einem kurzen Präfix, das die Art benennt, gefolgt von 32 Hexadezimalzeichen.

Verweise zwischen Objekten

Objekte verweisen über IDs aufeinander, in Feldern mit dem Namen <object>_id: collection_id, owner_id, folder_id. Um das verknüpfte Objekt in derselben Antwort zu erhalten, verwenden Sie expand[].

Pfadparameter, die eine ID erwarten, sind genauso benannt: {card_id}, {webhook_id}, {upload_id}.

Sammlungen über ihre ID

Sammlungen haben sowohl eine id als auch einen eindeutigen name, etwa support. Pfade, die es schon gab, bevor IDs bevorzugt wurden, erwarten den Namen der Sammlung:

GET /v1/collections/support/stats

Dieselben Pfade akzeptieren auch die ID, geschrieben als id:<number>:

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

Verwenden Sie in neuem Code bevorzugt die Form id:: Eine Sammlung kann von der Administration umbenannt werden, ihre ID bleibt aber dieselbe. Ein Segment nur aus Ziffern, etwa /v1/collections/3, bedeutet weiterhin die Sammlung mit dem Namen 3. Ein Sammlungsname kann kein : enthalten, sodass sich die beiden Formen nie vermischen.

In Bodys von Anfragen und in Query-Parametern steht collection_id neben dem früheren collection (dem Namen). Wenn Sie beide übergeben, gilt collection_id. Eine collection_id, die es in der Organisation nicht gibt oder die der Schlüssel nicht sehen darf, ergibt 404 mit dem Code collections.not_found.

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

Eigene IDs

Karten können in external_id die ID des Datensatzes tragen, aus dem sie in Ihrem System stammen: bis zu 512 Zeichen, eindeutig unter den Karten der Organisation. Damit müssen Sie die Sursa-ID einer Karte nie speichern:

Endpunkt	Was er tut
`PUT /v1/cards-by-external-id/{external_id}`	Erstellt die Karte oder ersetzt ihren Inhalt, wenn es sie gibt.
`GET /v1/cards-by-external-id/{external_id}`	Liest die Karte.
`GET /v1/cards?external_id=…`	Findet die Karte in einer Liste, zusammen mit anderen Filtern.

Kodieren Sie die external_id für die URL, wenn sie Teil des Pfads ist: Aus crm/A-1042 wird crm%2FA-1042.

Dokumente einer benutzerdefinierten Quelle haben innerhalb ihrer Quelle eine eigene external_id. Die beiden kommen sich nicht in die Quere: Eine Karte einer benutzerdefinierten Quelle ändern Sie, indem Sie das Dokument erneut an seine Quelle senden, nicht mit PUT /v1/cards-by-external-id/… – dieser Endpunkt antwortet in diesem Fall mit 409 und dem Code cards.managed_by_source.