Skip to main content

Basic concepts

In RAW, endpoints are created in the (web-based) integrated development environment using the Snapi programming language. These endpoints are then hosted and administered directly form the platform.

Creating API endpoints from Snapi code

Any Snapi expression can be turned into an API endpoint.

The simplest expressions like 1+1 can be used to generate a valid API output. It needs to be set in a function, typically called main, as in:

main() = 1 + 1

Of course, things more useful can be done with expressions. For instance if we want to check which products are low on stock from a MySQL table, we would create something like the following:

main() =
data = MySQL.InferAndRead("mysql001", "products")
Collection.Filter(data, x -> x.stockcount < 5)

This endpoint returns all rows of the MySQL table where stockcount is less than 5.

Handling query parameters in API endpoints from Snapi code

It is possible to pass parameters to functions:

main(name: string) = "Hello " + name + "!"

Parameters can also have default values:

main(name: string = "Anonymous") = "Hello " + name + "!"

As we've seen before, endpoints are mapped to functions. Typically, an endpoint executes the function called main. The function declaration, i.e. its arguments and their data types, will determine the endpoint behavior regarding parameters.

For instance:

main(name: string) = ...

This would map to an API endpoint that requires a query parameter name, as in https://<organization-url>/<endpoint-path>?name="Joe".

If the function argument is optional, as in:

main(name: string = "Anonymous") = ...

.. then the API endpoint has an optional query parameter name. It can then be called as:

  • https://<base_url>/endpoint, where name becomes "Anonymous";
  • or https://<organization-url>/<endpoint-path>?name="Joe", where name becomes "Joe".

There is an automatic conversion of query parameters into Snapi data types. For instance, if your function is declared to receive a parameter of type date, then a certain text syntax for dates is supported in the query parameter. For more information, refer to the Endpoint protocol.

Output data types

As discussed previously, endpoints execute Snapi code. Therefore, what the function returns is dependent on the Snapi code used.

The following will generate a collection of string (ID):

foo() =
data = MySQL.InferAndRead("mysql001", "products")
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 by specifying the return type as part of the function definition. This is usually a good idea to make sure we don't accidentally change the output type when we change the Snapi code.

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.