[TYPE 1] [Collections]

[jorwoods]

Summary

Support Collections endpoint

Request Type

If you know, say which of these types your request is in the title, and follow the suggestions for that type when writing your description.

Type 1: support a REST API:
If it is functionality that already exists in the REST API, example API calls are the clearest way to explain your request.

Description

CRUD operations for collections are support in 3.28+. Add support into TSC.

Please assign this issue to me.

[jorwoods]

The Collections API endpoints return JSON by default. They can be made to return XML by passing in the correct request header. Regarding adding the support, I have a few questions.

1. Should the Collections endpoints operate in JSON, their default, or XML the way most of TSC does?
2. The fields within the collections endpoint to "List items in a collection" don't have the same structure as what is returned by the rest of the XML endpoints. E.G. for workbooks, owner details are not nested under an owner element. Tags are <tags><value>some tag</value></tags> instead of <tags><tag>some tag</tag></tags>. So even if the XML is used, the parsing will have to follow separate paths.
3. If the we decide not to include full object parsing directly in the Collections listing, does it support anything like fields so we can reduce network traffic of unused XML attributes?
4. The "List Items in a collection" XML contains a "position" attribute on the item element. This value is negative. Can you help me understand this value? Is a closer to 0 value earlier or later in the collection?
5. The official API docs don't contain any details on the various error codes and what they might mean. Should I try to parse these into ServerResponseErrors or something else?
6. There are values like id, ownerId, siteId, etc. that are purely numeric and not UUID4s like I am used to seeing. Do we need to do anything with those IDs? Do they correspond to IDs returned by other REST or Metadata endpoints?

[jacalata]

Thanks for the great questions — here are answers from the server-side implementation:

1. JSON vs XML?
Both are equally supported server-side. Since TSC uses XML throughout, I'd recommend sticking with XML for consistency.

2. Why is the XML structure different for List Items?
This is intentional. The Collections service uses a reflection-based adapter (CollectionItemContentAdapter) that serializes content items by reflecting on the content type's methods via @ContentFieldDefinition annotations. This produces a flat structure — owner fields come out as siblings (ownerId, ownerName, etc.) rather than nested under <owner>. The <value> tag for list items (including tags) is the adapter's generic list serialization pattern, not tags-specific. So yes, the parsing will need separate paths from the standard endpoints.

3. Does it support fields to reduce network traffic?
No — the only query parameters supported are sort, filter, pageSize, page, and search. No field selection.

4. What does the negative position value mean?
The negative positions come from how items are inserted: each time you add items, the server finds the current minimum position and assigns minPosition - 1 to new items, so new items always land at the front of the list. A fresh collection starts at 0, so the first item added gets position -1, the next batch gets -2, -3, etc. More negative = earlier/first in the collection.
This is a transient state. Once you call PATCH .../orderItems to reorder anything, verifyAndFixPositions rewrites all positions as sequential integers (1, 2, 3...) and the negatives disappear. After that point positions are stable positive integers.
So in practice: sort by position asc to get correct order regardless of whether you're in the negative or positive regime.

5. Error codes — parse into ServerResponseError?
Collections has its own set of 16 error codes in the range 450xxx:
COLLECTION_NOT_FOUND (450404), PERMISSION_DENIED (450403), DUPLICATE_KEY (450409), INVALID_LUID (450008), TOO_MANY_ITEMS (450013), COLLECTIONS_NOT_ENABLED (450014), TOO_MANY_COLLECTIONS (450015), etc. These are distinct from general REST error codes. I'd parse them into ServerResponseErrors like we do elsewhere — the codes are distinct enough to be meaningful.

6. Are the numeric IDs useful?
The numeric id, ownerId, and siteId values are internal database PKs — not the same IDs used elsewhere in the REST API and not useful for interoperability. Content items (workbooks, views, datasources, flows, and projects) all expose a luid field within the item's content block. That luid is a standard UUID4 and matches the identifier returned by the normal REST API endpoints. TSC should use luid rather than id when cross-referencing collection items with other endpoints.