Skip to main content

Basic concepts

In RAW, endpoints can be written in different programming languages including SQL and Snapi. Moreover, you can use your own development environment or alternatively, the built-in web based integrated development environment. We recommend the latter to get started. These endpoints are then hosted and administered directly form the platform.

Let's see the basic concepts of building APIs in RAW:

Creating endpoints using Snapi​

info

For more information on Snapi and its support in RAW, you may also check the following Snapi reference guide.

Snapi expressions are turned automatically into an API endpoint. For instance, 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() =
    let
        data = MySQL.InferAndRead("mysql001", "products")
    in
        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 Snapi​

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 in Snapi​

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() =
    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 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.

Creating endpoints using SQL​

info

For more information on SQL and its support in RAW, you may also check the following SQL reference guide.

SQL queries are turned automatically into an API endpoint. For instance, a query such as:

SELECT name, address FROM db01.contacts

... is automatically converted into an API, which, when executed, returns a list of name and addresses that are read from the table "contacts".

Handling query parameters in SQL​

APIs in RAW can receive parameters. In SQL, query parameters are defined using a special syntax, which consists of a colon followed by the query parameter name.

For instance, if you define an API such as:

SELECT * FROM db01.airports WHERE iata_faa LIKE :iata

Notice the condition iata_faa LIKE :iata.

The ":iata" SQL syntax automatically defines a query parameter called "iata". If you create an API with code above, then this API requires a parameter called "iata", which is mandatory and must be passed by the user to call the endpoint.