# Configuration

A Rosetta deployment is formed from named resources known as 'entities'. There are four kinds of entity defined within the core Rosetta framework: views, providers, glyphs and profiles.

A view is a configurable REST API endpoint, bound to one or more path patterns and HTTP methods. They typically form a wrapper around lower-level Rosetta service methods, such as a DataService request, allowing both the raw request and response to be manipulated dynamically with custom transforms.

View requests are fulfilled by 'view executors', which are instances of classes that implement the ViewExecutor interface. All view executors receive an object that represents an HTTP request, modelled using the HttpDataRequest schema. An example HTTP request object rendered as JSON is as follows:

{
  "uri": "/my/example/view",
  "host": "0.0.0.0",
  "protocol": "HTTP/1.1",
  "scheme": "http",
  "method": "GET",
  "query": {
    "example_query_string": "query string value"
  },
  "headers": {
    "host": "localhost:4923",
    "user-agent": "curl/8.9.1",
    "accept": "*/*"
  }
}

There are different types of view, and the view's type determines the behaviour that occurs when a view receives a request. The type also affects what properties are available for configuration.

A list of built-in view types can be found on the Entity Reference page. See documentation for individual plugins for other view types.

A Provider is a data source in Rosetta. It is responsible for accepting requests, communicating with some external resource (such as a remote service or a local file), then providing Rosetta with the set of individual results or records. Providers may also offer metadata associated with the result set as a whole, such as aggregations or statistics.

There are different types of Provider, each defining its own behaviour and custom properties. The type may be selected for a specific Provider using its type configuration property.

For instance, a Provider named my-provider of type elasticsearch may be declared by including the following YAML structure in the rosetta.provider.providers[] array within the application.yml:

name: my-provider
type: elasticsearch
properties:
  protocol: http
  host: localhost
  port: 9200
  index: my-index

The set of available types of Provider may be extended (in a plugin, for instance) using Rosetta's Programming API, specifically by implementing the SPIs Provider and ProviderFactory.

A list of built-in Providers and their types is available here. For providers defined in a plugin, see the respective plugin documentation.

A Glyph is a configurable data transform. Glyphs behave as unary operators that take some input and produce an output. The specific forms for the input and output depend on the context in which they are invoked.

In the data phase of a data service request (see Profiles) for instance, the input is an individual result from the provider and the output is the transformed version of that same result as it should be rendered in the final response.

In most cases, multiple Glyphs may be chained together in a single transform phase, so that the output of one Glyph will be used as the input of another.

There are different types of Glyph, each defining its own behaviour and custom properties. The type may be selected for a specific Glyph using its type configuration property.

For instance, a Glyph named my-glyph of type elastic-generic-search may be declared by including the following YAML structure in the rosetta.transform.glyphs[] array within the application.yml:

name: my-glyph
type: elastic-generic-search
properties:
  search_config:
    search_fields:
      - field: _anywhere
      - field: id
        boost: 2.0

The set of available types of glyph may be extended (in a plugin, for instance) using Rosetta's Programming API, specifically by implementing the SPIs Glyph and GlyphFactory.

A list of built-in Glyphs and their types is available here. For glyphs defined in a plugin, see the respective plugin documentation.

A Profile is an entity that is used to coordinate the dataflow of Rosetta data service requests. It specifies the providers and transforms to be used in a Rosetta data request and determines the set of profiles allowed for a given endpoint or view.

For instance, a Profile named my-profile may be declared that selects only the provider named my-provider and applies a Glyph named my-request-transform to the incoming Rosetta request, and one named my-data-transform to each record that the provider yields. Such a Profile would be declared by including the following YAML structure in the rosetta.profile.profiles[] array within the application.yml:

name: my-profile
providers:
  policy: list
  names:
    - my-provider
transforms:
  request:
    - glyphs:
        policy: list
        names:
          - my-request-transform
  data:
    - glyphs:
        policy: list
        names:
          - my-data-transform

The profile can then be invoked my specifying the profile name in the View config, or as part of a data service request (e.g. the result of a View request transform).