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.

Minimal Example

A basic 0.11 definition with only the required fields:

raw: "0.11"            # Endpoint spec version (required)
httpMethod: GET        # Allowed: GET, POST, PUT, DELETE
metadata:
    title: "My Minimal Endpoint"   # 'metadata.title' is mandatory
codeLanguage: snapi    # Allowed: snapi, sql
codeFile: "../code.snapi"
format: json           # Allowed: json, csv, text, binary

This defines an endpoint that:

• Responds to GET requests.
• Uses a SNAPI file ../code.snapi.
• Outputs JSON format.
• Has minimal metadata (a title).

Full Example

A fully loaded sample with all fields:

raw: "0.11"
httpMethod: POST
metadata:
    title: "My Full Endpoint"
    description: "Demonstrates all fields in version 0.11"
    tags:
        - advanced
        - example
    termsOfService: "https://example.com/tos"
    author: "Jane Doe"
    contact:
        name: "Tech Support"
        url: "https://example.com/contact"
        email: "support@example.com"
    license:
        name: "Apache-2.0"
        url: "https://www.apache.org/licenses/LICENSE-2.0"
    version: 1.2
codeLanguage: snapi
codeFile: "../function.snapi"
format: csv
parametersLocation: body   # For POST/PUT, defaults to 'body'
mime-type: "text/csv"
declaration: "my_function"
security:
    public: false
    scopes:
        - sales
computeClass: normal
computeLimitSeconds: 10
cacheSizeMB: 200
expireSeconds: 60
enabled: true
tests:
    -   name: "Basic test"
        description: "No arguments"
    -   name: "Test with arguments"
        arguments:
            -   key: "customer"
                value: "ABC"

---

Definition of Fields

Below are the top-level fields and their descriptions. Detailed tables for metadata, security, and tests follow.

Top-level fields

Field	Type	Required	Description
raw	string	yes	Endpoint definition version. Must be "0.11".
httpMethod	string	yes	HTTP method. Allowed values: GET, POST, PUT, DELETE.
metadata	object	yes	Metadata about the endpoint. Must contain at least title. (See Metadata object fields).
codeLanguage	string	yes	Code language. Allowed values: snapi or sql.
codeFile	string	yes	Relative path to the code file in this repository.
format	string	yes	Output format. Allowed: json, csv, text, binary.
parametersLocation	string	no	Where parameters are read from: query or body. Defaults to query if httpMethod is GET/DELETE, and body if POST/PUT. Note: If httpMethod is GET, parametersLocation must be query.
mime-type	string	no	Custom MIME type (e.g., text/csv). If mime-type is defined, format will be ignored
declaration	string	no	Function name in the code file to run. If omitted, the code itself must evaluate to an expression.
security	object	no	Security policies. Defaults to public: false and empty scopes. (See Security object fields).
computeClass	string	no	Compute class. Currently only "normal" is supported.
computeLimitSeconds	integer (>=1)	no	Maximum runtime in seconds before execution is interrupted.
cacheSizeMB	integer (>=1)	no	Cache size in MB for caching results.
expireSeconds	integer (>=0)	no	Cache expiration in seconds. 0 means no caching.
enabled	boolean	no	Whether the endpoint is active. Defaults to true.
tests	array of objects	no	A collection of test cases. See Tests object fields.

---

Metadata object fields

Field	Type	Required	Description
metadata.title	string	yes	A short display title for the endpoint.
metadata.description	string	no	A longer description or summary.
metadata.tags	string[]	no	A unique list of tags describing the endpoint.
metadata.termsOfService	string	no	Terms of service or a link.
metadata.author	string	no	The author or owner of the endpoint.
metadata.contact	object	no	Contact information (requires a name). See below.
metadata.license	object	no	License reference (requires a name). See below.
metadata.version	string | number	no	A version label or number for the endpoint.

metadata.contact fields:

Field	Type	Required	Description
metadata.contact.name	string	yes	Contact person or team name.
metadata.contact.url	string	no	URL for more info or support.
metadata.contact.email	string	no	Email address for contact.

metadata.license fields:

Field	Type	Required	Description
metadata.license.name	string	yes	License name, e.g. "MIT", "Apache-2.0".
metadata.license.url	string	no	URL pointing to a license page or text.

---

Security object fields

Field	Type	Required	Description
security.public	boolean	yes	If true, the endpoint is public. If false, only authenticated users with matching scopes can access.
security.scopes	string[]	no	One or more scopes required for access. A token containing at least one of these scopes is permitted.

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.11.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 (>=3 chars)	yes	A short identifier for the test case.
tests[].description	string	no	Longer explanation of what the test checks.
tests[].arguments	array of objects	no	A set of key-value pairs representing query parameters for the endpoint.

arguments array items:

Field	Type	Required	Description
key	string	yes	The name of the argument.
value	string	yes	The corresponding value.

---

Migrating from Older Versions (0.9 or 0.10)

To move from 0.9 or 0.10 to 0.11:

1. Schema version

   • Change raw: "0.9" / raw: "0.10" to raw: "0.11".

2. Method field

   • Old: endpoint: GET
   • New: httpMethod: GET

3. Language field

   • Old: code: snapi / code: sql
   • New: codeLanguage: snapi / codeLanguage: sql

4. Metadata requirement

   • Now required. At least metadata.title is needed.

5. Parameters location

   • parametersLocation defaults to query for GET/DELETE, body for POST/PUT.
   • For GET, only query is valid.

6. Expire seconds

   • Now can be 0 to disable caching.

7. Other adjustments

   • Ensure renamed fields match the 0.11 schema.
   • Remove any fields that are not supported in 0.11.