diff --git a/docs/8.0/ayanova/docs/form-ay-report-edit.md b/docs/8.0/ayanova/docs/form-ay-report-edit.md index 12193593..7af5fe91 100644 --- a/docs/8.0/ayanova/docs/form-ay-report-edit.md +++ b/docs/8.0/ayanova/docs/form-ay-report-edit.md @@ -254,7 +254,70 @@ You should not store a static copy of an API Bearer access token or hard code it While it is possible to login via a script using alternate credentials and access the API with alternative access to the current logged in user, this opens a security hole as you would need to hard code credentials into the report script and is **absolutely NOT recommended**. -The following is a simple example of access the API via a Helper to retrieve a value: +### API convenience functions + +Two functions are provided with the report to assist with API usage from your ayPrepareData custom function: + +*GET* + +The ayGetFromAPI function works with GET routes in the API: + +```async function ayGetFromAPI(route, token) {...``` + + +*POST* + +The ayPostToAPI function works with POST routes in the API: + +```async function ayPostToAPI(route, token, data) {...``` + + +*Parameters* + +The `route` parameter should be the complete route to the api method required and can be constructed from the meta data provided to the report, for example to fetch data from the `server-info` API route: +```let route=`${reportData.ayServerMetaData.ayApiUrl}server-info`;``` + +The `token` parameter is the authorization token provided in the Client data as follows: +```let token=reportData.ayClientMetaData.Authorization;``` + +The `data` parameter of a POST route differs for each route and is documented in the developer's API documentation. + +The following is an example of accessing the API with both a GET and POST action: + +``` +async function ayPrepareData(reportData) { + + //Example API GET method + //to fetch data from API server + //using the "server-info" route + + let route=`${reportData.ayServerMetaData.ayApiUrl}server-info`; + + //Add the data to the main report data object + //so it's available to the template + reportData.myData= + { + ServerInfo:await ayGetFromAPI( + route, + reportData.ayClientMetaData.Authorization + ) + }; + + //Example API POST method to fetch data from api server + //using the "search" route + route=`${reportData.ayServerMetaData.ayApiUrl}search`; + + //construct the POST object + let searchPostData={phrase: "Fish"}; + + reportData.myData.SearchResults = await ayPostToAPI( + route, + reportData.ayClientMetaData.Authorization, + searchPostData + ); + return reportData; +} +```