ListCollections is documented but returns 501 — and the API doc now makes that the first thing a user clicks

[hsinatfootprintai]

GET /v1/projects/{projectId}/collections — "list collections" — is declared in the OpenAPI spec and returns 501 not implemented.

$ curl -H "X-Api-Key: …" https://ucairc.ubm.ac.id/reststore/v1/projects/59/collections
{"code":12,"message":"code(10), not implemented","details":[]}

It is the only documented GET that does not work. Everything else on the same project answers:

endpoint
GET /collections	501
GET /collections/{id}	200
GET /collections/{id}/docs	200
GET /apidoc	200
GET /collections/{id}/apidoc	200
POST /collections	200

Why it matters more than it did last week

Until #143 the Swagger UI pointed at Swagger's public demo API, so nobody could try any of these. Now that /reststore serves the real doc with a working Try it out, "list my collections" is the first thing a person will click — it is the only one of the nine that needs no prior knowledge. The first impression of the API is a 501.

It is also the natural first call for any client: you cannot GET /collections/{id} without already knowing an id.

What is already in place

pkg/app/collections.go:62

// ListCollections is not yet implemented.
func (r *RestColServiceServerService) ListCollections(ctx context.Context, req *apppb.ListCollectionsRequest) (*apppb.ListCollectionsResponse, error) {
	return nil, sderrors.NewNotImplError(errors.New("not implemented"))
}

The storage layer it would need already exists:

// pkg/storage/collections/collections.go:59
func (c *CollectionCURD) ListByProjectID(ctx, tableName string, pid ProjectID) ([]*ModelCollection, error)

The one real decision

ListCollectionsResponse is empty:

message ListCollectionsResponse {}

So this is not a handler fill-in — it needs a response shape, a proto change, and regeneration. That is an API design call, which is why I am filing it rather than picking one. The obvious candidates:

1. repeated CollectionMetadata collections — metadata only, cheapest, matches what a picker needs.
2. repeated GetCollectionResponse collections — metadata + description + type + schemas, consistent with the single-collection GET, heavier.
3. Option 1 plus pagination now rather than later, since this is the endpoint that grows with the tenant.

Worth deciding alongside: ListByProjectID returns every row including every schema version, so whether "list" means collections or collection-versions needs to be pinned down.

Aside

/v1/projects/{projectId}/apidoc and /v1/projects/{projectId}/collections/{collectionId}/apidoc both work and return a per-scope swagger document. That answers an open question from FootprintAI/grandturks#1198 — they are live, not aspirational.