Endpoint configuration

Endpoints are defined as YAML files.

The endpoint YAML file defines code, metadata, security and deployment settings for an endpoint.

Endpoint YAML files can be located anywhere in the repository tree. The path of the file will become the deployment URL, without the .yml extension.

See the YAML Overview for more information about the folder structure.

Example

This file defines an endpoint at /path/to/my-endpoint, which responds to HTTP GET requests by executing the declaration my_function defined in file ../codefile.snapi in the normal compute class. The endpoint is enabled, has a maximum computation limit of 10 seconds. Its cache is used unless cached data from previous executions is older than 10 seconds. The endpoint is secured - so the user must present an access token - and the access token must contain scope sales. The metadata information such as title, descritpion and tags are used to populate RAW's metadata catalog.

/path/to/my-endpoint.yml example

raw: "0.10"  # Endpoint spec file version (required)
endpoint: GET # HTTP method only GET is allowed (required)
#
# Endpoint metadata (optional)
#
metadata:
  title: My example endpoint
  description: This is my example endpoint!
  tags:
    - example
    - sales
#
# Endpoint code
#
code: snapi # "snapi" and "sql" are accepted (required)
codeFile: ../codefile.snapi # Relative path to the code file in this repository (required).
declaration: my_function # Declaration in the code file to use for this endpoint (optional). If not specified, code must evaluate to an expression.
#
# Endpoint security (optional)
# Default is secure with no scopes.
#
security:
  public: false # If not specified defaults to false.
  scopes: # Only users or apps with the following OAuth scopes can access this endpoint.
    - sales
#
# Endpoint deployment settings
#
format: json # Output format, available options: json, csv, text or binary (required)
computeClass: normal # Compute class/resources for this service. (required)
enabled: true # If not specified defaults to true.
cacheSizeMB: 200
computeLimitSeconds: 10
expireSeconds: 10 # If not specified, cached data does not expire.
tests:
  - name: ATest without arguments # Required
    description: a simple test without arguments
  - name: ATest with arguments # Required
    description: a simple test with arguments
    arguments:
      - key: arg1
        value: value_of_arg

Definition

Field	Type	Required	Description
raw	string	yes	Endpoint spec version. Accepted values: "0.10"(default), 0.9(deprecated), "0.9"(deprecated).
endpoint	string	yes	HTTP method. Accepted values: GET.
code	string	yes	Programming language. Accepted values: snapi, sql.
codeFile	string	yes	Relative path to the code file in this repository.
format	string	yes	Endpoint output format. Accepted values: json, csv, text, binary.
computeClass	string	yes	Computational class to use. Accepted values: normal.
enabled	boolean	no	Indicates if the endpoint is enabled, defaults to true
cacheSizeMB	integer	no	Cache size in megabytes.
computeLimitSeconds	integer	no	Number of seconds threshold before compute task is interrupted.
declaration	string	no	Function in the code file to use for this endpoint (optional). If not specified, code must evaluate to an expression.
metadata	object	no	Endpoint metadata object, see Metadata object fields.
security	object	no	Security object, if not specified defaults to public false and with empty scopes.
expireSeconds	integer	no	Cache time-to-live in seconds before expiring, requiring a new execution.
tests	array	no	An array of test cases to test the endpoints with or without arguments

Metadata Object fields

Field	Type	Required	Description
metadata.title	string	yes	Endpoint title.
metadata.description	string	no	Endpoint (extended) description.
metadata.tags	string	no	Multiple tags to describe the endpoint.

Security Object fields

Field	Type	Required	Description
security.public	boolean	yes	Indicates if the endpoint is public or private.
security.scopes	string	no	Only users or apps with the defined scopes in their access token can access this endpoint.

general rules for scopes

You can define an array of scopes in the definition. Any user that contains at least one of the defined scopes of the endpoint definition will be able to list and execute the endpoint.

Maximum length allowed for each scope: 256 characters

Regular expression pattern that permits scope values: see endpoint-schemaV0.10.json

Examples of allowed scope literals:

• examplescope
• example:scope
• example-scope
• example_scope
• another-example:scope
• another_example:scope_1
• another_example:scope_2
• another_example:a1
• another_example:a-1

Examples of not allowed scope literals:

• no spaces allowed
• not::allowed
• :invalid
• not_allowed_2_dashes_with_double_colon:any
• not_allowed_with_more_dashes:1
• not_allowed_with_more_dashes:any
• not-allowed-more:1
• not-allowed:1
• not-allowed:-asdf
• ::::::::
• ----:____
• ----
• ____

Tests Object fields

Field	Type	Required	Description
tests.name	string	yes	A name to identify a test case. This name will be shown in test browser.
tests.description	string	no	A description of what this test tests in a readable form. This description will be shown in test browser.
tests.arguments	string	no	A collection of key-value pairs for endpoints that are able to take url query parameters when fetching data.
tests.arguments.key	string	yes if arguments are defined	The a unique name of an argument
tests.arguments.value	string	yes if arguments are defined	A collection of key-value pairs for endpoints that are able to take url query parameters when fetching data.