Skip to main content

Configuring APIs

Setting the output format​

Function returns​

Function and endpoints are tightly related. What the function returns is dependent on the Snapi statement used. The following will generate a collection of string (ID):

foo() =
    let
        data = MySQL.InferAndRead("mysql001", "products")
    in
        Collection.Transform(x -> { id: x.product_id })

However, it is possible to describe in the function declaration what the output will look like. This is done with the following syntax :

foo() : collection(string) = ...

Here, the foo() function will return a collection of strings. Of course, the notation much match the output of the statement otherwise the expression will generate a compilation error.

Defining custom types​

type can be used to declare what the function return will look like. This makes things reusable and more readable.

let
    type foo_return := record(
        data:collection(string),
        cnt:int
    )
in
    foo(): foo_return = ...

This will produce a Snapi result like, for instance:

{
    data: [
        "blue",
        "black",
        "yellow"
    ],
    cnt: 3
}

In the Snapi syntax, curly braces {} denote records and brackets [] are collections.

Output format​

The endpoint output format (ie. how the function output is going to render), is set in the {endpoint}.yml file through the format field and can take the following values:

format value
json
csv

Securing APIs​

There are two types of APIs in RAW:

  • public APIs, which can be accessed by anyone in the public, without having to be authenticated or authorized;
  • private APIs, which required the user to be authenticated and authorized.

Public APIs​

To declare a public API, add the following definition to the endpoint YAML file:

security:
  public: true

A public endpoint can be access by anyone without any authentication or authorization.

For more information on the endpoint YAML definition, consult our reference guide.

Attention

Public APIs should be used carefully as any execution costs will be incurred on your account.

Private APIs​

To declare a private API, add the following definition to the endpoint YAML file:

security:
  public: false

This is the default in case the security section is not included.

A private endpoint can only be accessed by members of the organization. Therefore, a valid OAuth access token must be included in the HTTP request.

In addition, private endpoints can have additional authorization restrictions in the form of scopes. Scopes are a list of strings included in the OAuth access token. Only tokens containing those scopes are authorized to access the endpoint.

For instance, assume an endpoint defined as:

security:
  public: false
  scopes:
    - department_head
    - hr

This endpoint can only be accessed by users or applications whose scopes include 'department_head' and 'hr'. All other users will not be authorized to access the endpoint.

In order for your clients to be able to execute a private endpoint, you can provide them with an API key that is associated to at least one scope that your endpoint has defined.

For more information on the endpoint YAML definition, consult our Endpoint configuration guide.

For more information on the endpoint protocol, consult our protocol guide.

Accessing User Scopes in Snapi​

Scopes Keyword​

Its possible to access user scopes using the function Environment.Scopes. This is a list of strings and corresponds to the scopes/permissions of the user calling the endpoint.

For example the following function will return a different output depending if the user calling it has the scope "special" in his permissions.

Function querying scopes
special() =
    if (List.Contains(Environment.Scopes(), "special"))
    then "you are special"
    else "you are not special"