Skip to main content

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.


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)
title: My example endpoint
description: This is my example endpoint!
- 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.
public: true # 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.
- name: ATest without arguments # Required
description: a simple test without arguments
- name: ATest with arguments # Required
description: a simple test with arguments
- key: arg1
value: value_of_arg


rawstringyesEndpoint spec version. Accepted values: "0.10"(default), 0.9(deprecated), "0.9"(deprecated).
endpointstringyesHTTP method. Accepted values: GET.
codestringyesProgramming language. Accepted values: snapi, sql.
codeFilestringyesRelative path to the code file in this repository.
formatstringyesEndpoint output format. Accepted values: json, csv, text, binary.
computeClassstringyesComputational class to use. Accepted values: normal.
enabledbooleannoIndicates if the endpoint is enabled, defaults to true
cacheSizeMBintegernoCache size in megabytes.
computeLimitSecondsintegernoNumber of seconds threshold before compute task is interrupted.
declarationstringnoFunction in the code file to use for this endpoint (optional). If not specified, code must evaluate to an expression.
metadataobjectnoEndpoint metadata object, see Metadata object fields.
securityobjectnoSecurity object, if not specified defaults to public false and with empty scopes.
expireSecondsintegernoCache time-to-live in seconds before expiring, requiring a new execution.
testsarraynoAn array of test cases to test the endpoints with or without arguments

Metadata Object fields

metadata.titlestringyesEndpoint title.
metadata.descriptionstringnoEndpoint (extended) description.
metadata.tagsstringnoMultiple tags to describe the endpoint.

Security Object fields

security.publicbooleanyesIndicates if the endpoint is public or private.
security.scopesstringnoOnly 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

tests.namestringyesA name to identify a test case. This name will be shown in test browser.
tests.descriptionstringnoA description of what this test tests in a readable form. This description will be shown in test browser.
tests.argumentsstringnoA collection of key-value pairs for endpoints that are able to take url query parameters when fetching data.
tests.arguments.keystringyes if arguments are definedThe a unique name of an argument
tests.arguments.valuestringyes if arguments are definedA collection of key-value pairs for endpoints that are able to take url query parameters when fetching data.