Give a more distinct name to the structure family currently called "node"

[danielballan]

In Tiled we have defined structure families:

tiled/tiled/structures/core.py

Lines 12 to 16 in 6b1ee86

	class StructureFamily(str, enum.Enum):
	node = "node"
	array = "array"
	dataframe = "dataframe"
	sparse = "sparse"

One them is "node". It is a container that has no structure or data in itself, but it has children. It may correspond to a directory, a dictionary-like object, an HDF5 group, or any similar structure.

Confusingly, we also use the word "node" to refer to any object in tiled, whatever its structure. To give just one example, the endpoint /node/metadata/x/y/z accesses the metadata for the node at /x/y/z whether it's an "array" or "dataframe" or "node". We have received feedback from several directions that this is very confusing.

I propose to change

• StructureFamily.node -> StructureFamily.container
• tiled.client.Node -> tiled.client.Container

This is an important change but it is a fairly targeted one that I think will not affect very much code. Some aspects can be made backward-compatible, but not all.

Other names considered but rejected in favor of "container":

• tree
• mapping
• group
• collection

Discussed with @dylanmcreynolds

[danielballan]

While we're at it I think we should simplify our URLs from /node/metadata, /node/search and /node/distinct to just /metadata /search and /distinct. The /node prefix made sense early on but now it's just extra typing.

From the perspective of "documentation-driven development" I like the idea of teaching...

http :8000/api/v1/metadata
http :8000/api/v1/search

That's still a bit of a mouthful due to the /api/v1 namespace, but it's one step more memorable than :8000/api/v1/node/metadata.

This can be done in a backward compatible way, with undocumented aliases or redirects.

[padraic-shafer]

My $0.02…

• “container” is a good name for these StructureFamily objects
• removing “node” from the URL paths is a useful simplification