docs: hasKey templating example (#4409)

rilldata · Mar 22, 2024 · 7d3d45d · 7d3d45d
1 parent 28f7cee
commit 7d3d45d
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 6 deletions.
diff --git a/docs/docs/integrate/custom-api.md b/docs/docs/integrate/custom-api.md
@@ -9,8 +9,14 @@ Rill exposes [custom APIs](/integrate/custom-apis/index.md) you have created und
 at `https://admin.rilldata.com/v1/organizations/<org-name>/projects/<project-name>/runtime/api/<api-name>`.
 
 ## Accessing custom APIs
-You need to do a POST request to the API endpoint with A bearer token in the `Authorization` header.
-
+Custom APIs accepts both POST and GET requests to the API endpoint with a bearer token in the `Authorization` header.
+For GET requests parameters can be passed in the url.
+
+```bash
+curl https://admin.rilldata.com/v1/organizations/<org-name>/projects/<project-name>/runtime/api/<api-name>[?query-args] \
+-H "Authorization: Bearer <token>"
+```
+
 ```bash
 curl -X POST https://admin.rilldata.com/v1/organizations/<org-name>/projects/<project-name>/runtime/api/<api-name>[?query-args] \
 -H "Authorization: Bearer <token>"

diff --git a/docs/docs/integrate/custom-apis/sql-api.md b/docs/docs/integrate/custom-apis/sql-api.md
@@ -20,11 +20,14 @@ where `my_table` is your model or source name.
 You can use templating to make your SQL query dynamic. We support:
  - Dynamic arguments that can be passed in as query params during api call using `{{ .args.<param-name> }}`
  - User attributes like email, domain and admin if available using `{{ .user.<attr> }}` (see integration docs [here](/integrate/custom-api.md) for when user attributes are available)
- - Conditional statements using go ang sprig templating functions (see resources at the end for more details) 
+ - Conditional statements 
+ - Optional parameters paired with conditional statements.
 
-For example:
+See integration docs [here](/integrate/custom-api.md) to learn how to these are passed in while calling the API.
+
+### Conditional statements
 
-`my-api.yaml`:
+Assume a API endpoint defined as `my-api.yaml`:
 ```yaml
 kind: api
 sql: |
@@ -37,7 +40,26 @@ sql: |
 will expose an API endpoint like `https://admin.rilldata.com/v1/organizations/<org-name>/projects/<project-name>/runtime/api/my-api?date=2021-01-01`.
 If the user is an admin, the API will return the count of `measure` by `dim` for the given date. If the user is not an admin, the API will return the count of `measure` for the given date.
 
-See integration docs [here](/integrate/custom-api.md) to learn how to these are passed in while calling the API.
+
+### Optional parameters
+
+Rill utilizes standard Go templating together with [Sprig](http://masterminds.github.io/sprig/) which adds a number of useful utility functions.  
+One of those functions is `hasKey` which in the example below enables optional parameters being passed to the Custom API endpoint. This allows you to build API endpoints that can handle a wider range of parameters and logic, reducing need to duplicate API endpoints.
+
+Assume a API endpoint defined as `my-api.yaml`:
+```yaml
+SELECT
+  device_type,
+  AGGREGATE(overall_spend)
+FROM bids
+{{ if hasKey .args "type" }} WHERE device_type = '{{ .args.type }}' {{ end }} 
+GROUP BY device_type
+```
+
+HTTP Get `.../runtime/api/my-api` would return `overall_spend` for all `device_type`'s  
+HTTP Get `.../runtime/api/my-api?type=Samsung` would return `overall_spend` for `Samsung`
+
+
 
 ## Useful resources