Naming Query Templates¶

Convention, non-normative. The service enforces only the grammar of a name (see the reference, chapter 10, Query Templates, and chapter 12, Naming Conventions); this page describes the convention the components of the infrastructure follow on top of it.

The rule¶

The name of a Query Template starts with the macro-group that owns it, followed by what the template returns:

<macro-group>-[all-]<object>[-by-<criteria>]

No verb: a Query Template is always a read, so get says nothing.
all- marks the complete list of a type, with no criteria narrowing it: catalogue-all-metadata-profiles, is-all-eservice.
-by-<criteria> marks a lookup narrowed by its variables. The object is singular when the intent is one resource (even if several equal copies may answer, e.g. the EService of a service deployed twice) and plural when the intent is a set: gcube-eservice-accesspoint-by-group-and-name, gcube-eservices-by-state.
Neither of them: the one resource of its kind in the Context, with no variables: catalogue-configuration. The whole name stays inside the grammar of the service: lowercase words separated by hyphens, ^[a-z][a-z0-9]*(-[a-z0-9]+)*$.

The name says who maintains the template and what it looks for, nothing more. The technology behind a resource does not enter the name: when it changes, a new version of the definition follows it and the name stays. Every other property of the answer, a projection first of all, is said by the description.

The description¶

The description is mandatory and it is what a caller reads to know what the template returns:

it starts with Returns and names the type of the instances returned, with the criteria the variables apply;
when the template projects the result with _emit, it says so and lists the fields returned (Projection: ...): the caller receives those fields, not the instances;
it does not describe the request body or the default values of the variables: each variable has its own description, and the default value of a variable only lets the service test the query.

Macro-groups¶

A new macro-group is added here when a new stack defines its first template.

Why the macro-group and not the component¶

Shared libraries. Many templates are installed and run by a library shared by several services (catalogue-core runs in gcat and in grsf-publisher). The macro-group names them without choosing one service as their owner.
Stable names. A function that moves from a service to its library, or a new service of the same stack, keeps the name of its templates.
Grouped listings. Sorted by name, the templates of a stack are listed together.
Generic queries are not owned by their first user. A query that any service could use (is- or gcube-) keeps the generic prefix even when a single component installs it or runs it today.
Clear ownership. The prefix tells which stack maintains the template and raises its version when its definition changes.

Changing a name¶

A Query Template is never renamed: the template with the new name is created at version 1.0.0 and the one with the old name is deleted once no client runs it any more.

Who installs a template¶

A service or a library installs the templates it runs at start-up, with its own token, through the versioned upsert (PUT /query-templates/{name}): the same definition is a no-op, a higher version updates it, and a 409 Conflict tells an outdated component that a newer definition is already installed.
The provisioning installs its templates with the token of the provisioning client.
The generic templates (gcube-) and the ones of the IS tools (is-) are part of the reference set installed by the Resource Registry migration.

The token that installs a template needs a role allowed to write Query Templates (IS-Manager, Infrastructure-Manager or IS-Admin). The registry records the identity that created a template in its metadata: together with the prefix, it tells who put it there and why.