RAW endpoint naming best practices

TL;DR

Endpoints: lower case nouns with hyphens like /customer /page /sports-news and verbs if they change the state of the program like /set-time

Clear names: /customer/metadata better than /cst-md

Camel case for query strings: /sports-news?newsId=”xxx”

Avoid reserved words whenever possible: /invoices?invoiceDate=”YYYY-MM-DD” better than /invoices?date=”YYYY-MM-DD”

Nouns or Verbs?

RAW endpoints operate HTTP GET methods, meaning that it is all about retrieving data. If you are building an endpoint to retrieve customers for instance, it should be named customers, not getCustomers because it is implicit.

If you want to retrieve customer metadata? You should go with https://{subdomain}.raw-labs.com/customers/metadata

In most naming conventions, verbs are used whenever they change the state of the program, thereby they should be used only if the endpoint does something different than returning data like https://{subdomain}.raw-labs.com/set-time?t=”12:00:00”

Using clear names

https://{subdomain}.raw-labs.com/cst-md or

https://{subdomain}.raw-labs.com/customer/metadata ?

which one is the easier to understand and to remember :blush:?

Hyphens, underscores, lowercase or camelCase?

Except for the host part, URIs are case sensitive; who would ever type in their browser search bar the following: HTTPS://WWW.GOOGLE.COM/SEARCH?q=”RAW Labs” ?

Choosing by convention to name all endpoints with lowercase names makes it much easier to remember them.

RAW endpoint names are derived from YML file names mapped to a RAW SQL function, to avoid any confusion endpoints should be in lowercase and may use hyphens.

RAW SQL functions and parameters are case insensitive, however the way they are typed in the code will impact the mapping and how they should be passed in the URI.

For instance, if the following function is declared

hello(customerName:string) := {
};

It is possible to reference CUSTOMERNAME in the function and it will work, but the parameter will be expected with the correct case in the URI https://{subdomain}.raw-labs.com/hello?customerName=”Joe”

Hyphens are not allowed in identifiers or function names; they would be interpreted as a minus - operator. Only underscores are admitted, however, traditionally identifiers in SQL are named after the snake_case naming convention therefore it makes sense to use the camel Case naming convention for parameters to distinguish them from other identifiers in the function.

Reserved keywords

Even though it is possible, we recommend avoiding as much as possible the use of reserved keywords in parameters. For instance

https://{subdomain}.raw-labs.com/invoices?invoiceDate=”2022-01-13

should be preferred over

https://{subdomain}.raw-labs.com/invoices?date=”2022-01-13

Versionning

It is recommended to use versioning in the URI like:

https://{subdomain}.raw-labs.com/v1/

https://{subdomain}.raw-labs.com/v2/