Skip to content

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

Prefix Owner Components
catalogue- the catalogue stack gcat, catalogue-core, gcat-client, grsf-publisher, the gcat plugins
accounting- the accounting stack accounting libraries and services, aggregator, dashboard harvester
is- the Information System stack queries of the IS tools themselves, e.g. the lists by Type of the IS GUI
gcube- gcube-model, which defines the Types these queries read generic queries offered to every gCube service and tool (the IS GUI among them) so that none writes them again: the base ones on relations and facets of any resource, and the ones on the gCube model (EService, SoftwareFacet, AccessPointFacet, ...)
uri-resolver- the URI Resolver stack uri-resolver, uri-resolver-manager, gcube-url-shortener
provisioning- the provisioning queries that only the provisioning (the Ansible playbooks and the collection gcube.resource_registry) needs

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.