Perfecto Server – API

Overview

The ApiCall represents an API request object, allowing Perfecto Server to interact with external APIs via REST calls. It supports both sending (upload) and receiving (download) data, as well as token-based authentication.

Key Features

• Supports GET and POST/PUT requests.
• Schedules API calls using CRON expressions.
• Handles token-based authentication using Bearer tokens.
• Allows dynamic and static parameter handling.
• Supports mapping API responses to database fields.
• Includes support for sub-records in API responses.

---

1. Fields and Properties

1.1 General Properties

• Name:
  • A required field to define the name of the API call.
• TokenCall:
  • Another ApiCall object responsible for generating an access token if authentication is needed. Token calls must be of DataDirection.Tokenization.
• ScheduleType:
  • Indicates if the API call is scheduled or on-demand. For scheduled tasks, a CRON expression is provided.
• CRONSchedule:
  • A CRON expression defining the frequency of the API call. This is hidden if ScheduleType is set to OnDemand.
• Active:
  • A boolean field determining if the API call is active and should be executed.
• Method:
  • Defines the HTTP method (GET, POST, PUT, etc.) for the API call.
• Direction:
  • Specifies whether the call is for downloading (receiving data from the API), uploading (sending data), or tokenization (for authentication purposes).

1.2 URL and Queries

• URL:
  • The API endpoint URL (required).
• ParametersSelectionQuery:
  • SQL query used to select dynamic parameters when making API calls.
• UpdateQuery:
  • SQL query to update the database with the API response data.
• SubrecordsUpdateQuery:
  • Similar to UpdateQuery, but for handling sub-records (nested records in API responses).

1.3 Database Mapping

• SelectSourceTable / SelectTargetTable:
  • Defines the source or target tables for data interaction.
• RetreivedRecordIdField:
  • Defines the primary key field used for identifying records in the database.
• Mapping:
  • A collection of mappings between API fields and database fields. This includes static values, dynamic values, and queries to perform data transformations.

1.4 Result Handling

• ResultType:
  • Specifies the structure of the API response, whether it’s an object, list, or string.
• ResultedFieldKey:
  • Key used to extract a specific field from the API response if the result is structured.

---

2. Making an API Call

2.1 Reading from API (GET Request)

To read data from an API using this ApiCall , follow these steps:

1. Define the API Call:
   • In the URL field, specify the API endpoint from which you want to retrieve data.
   • Set the Method property to GET.
   • If the API requires an access token, define a TokenCall.
2. Configure Parameters (Optional):
   • If your API requires query parameters, you can add them in the Parameters section of the UI.
   • Use the ParametersSelectionQuery if parameters are dynamically fetched from a database.
3. Define the Result Handling:
   • Set the ResultType based on how the API response is structured (Object, List, String).
   • Provide the ResultedFieldKey if you need to extract a specific field from the API response (e.g., an ID field).
4. Database Mapping (Optional):
   • Define how the API data should be mapped to your database tables using the SelectSourceTable or SelectTargetTable.
   • Use the Mapping section to map API response fields to database columns.
5. Schedule or Trigger:
   • Schedule the call using CRONSchedule or leave it for manual execution.
6. Execution:
   • When the API call is executed, it will:
     1. Fetch the data from the API.
     2. Parse the response using the provided mappings.
     3. Insert or update the database using the generated UpdateQuery.

---

2.2 Sending Data to an API (POST/PUT Request)

To send data to an API:

1. Define the API Call:
   • Set the URL field to the API endpoint where the data will be sent.
   • Set the Method to POST or PUT based on the API.
2. Configure Parameters:
   • Use the ParametersSelectionQuery to dynamically generate data that will be sent to the API.
   • Add the parameters to the Parameters section. Each parameter can be a static or dynamic value.
3. Token Call (Optional):
   • If authentication is required, use the TokenCall property to retrieve an access token.
4. Result and Update Handling (Optional):
   • If you expect a response from the API, define the result handling and mapping similar to a GET request.
5. Execution:
   • When the API call is executed, it will:
     1. Send the data to the API endpoint.
     2. If the call is successful, it can store the response and update the database accordingly.

---

3. Handling Tokens

If the API requires token-based authentication:

1. Create a Token API Call:
   • Set the Direction to Tokenization.
   • Define the URL to fetch the token.
   • Set the ResultedFieldKey to extract the token from the API response (usually in the access_token field).
2. Attach the Token Call:
   • In the primary API call, reference this TokenCall.
   • The system will automatically use the token for authentication when making the request.

---

4. CRON Scheduling

• Use the CRONSchedule field to automate the API calls. For example, "0 0/30 0 ? * * *" will trigger the call every 30 minutes.
• If you want the call to be triggered manually or by an external event, set the ScheduleType to OnDemand.

---

5. Error Handling

If the API call fails or encounters an error, the Log field will store the error message, and you can inspect it to troubleshoot the problem.

---

Conclusion

The ApiCall in your Perfecto Server module is a powerful tool for integrating external APIs. By configuring the fields for URLs, parameters, and result mappings, you can effectively communicate with APIs, automate requests, and manage the data received or sent. The combination of tokenization, CRON scheduling, and database mapping makes this system versatile for various use cases.

---

Example 1: Sending Data to a Well-Known API (POST Request to Slack API)

Scenario: You want to send a message to a Slack channel using Slack’s Incoming Webhook API.

Step-by-Step Guide:

1. Create the Slack API Call:
   • URL: Use Slack’s webhook URL for your workspace. Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX.
   • Method: Set the Method to POST.
   • Direction: Set Direction to UploadOnly because you are sending data.
   • Parameters:
     • Add a parameter for the message body. The parameter should be JSON-formatted, as Slack requires the message to be sent as JSON.
     • The JSON body could look like this:jsonCopy code{ "text": "Hello, this is a message from Perfecto Server." }
     • The message can be static or dynamic, depending on how you want to configure it.
2. Setup in the ApiCall:
   • Name: SendSlackMessage
   • URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
   • Method: POST
   • Parameters:
     • Key: message
     • Value:jsonCopy code{ "text": "Hello, this is a message from Perfecto Server." }
     • Parameter Type: JsonBody
     • ValueType: StaticValue (you can change this to dynamic based on your requirements).
   • Active: Ensure this API call is active.
3. Execute the API Call:
   • Once the API call is configured, you can execute it manually to send the message to your Slack channel.
4. Expected Outcome:
   • If successful, the message should appear in the designated Slack channel. The Log field in the Perfecto Server should show a success response, confirming that the API call was executed correctly.

---

Example 2: Fetching Records from a Well-Known API (GET Request to OpenWeather API)

Scenario: You want to retrieve weather data for a specific city using the OpenWeather API.

Step-by-Step Guide:

1. Create the OpenWeather API Call:
   • URL: Use OpenWeather’s endpoint for fetching weather data. Example: https://api.openweathermap.org/data/2.5/weather.
   • Method: Set the Method to GET.
   • Direction: Set Direction to DonwloadOnly because you are fetching data.
   • Parameters:
     • OpenWeather requires parameters such as:
       • q: The city name (e.g., "Cairo").
       • appid: Your API key from OpenWeather.
     • These parameters should be included as query parameters in the request.
2. Setup in the ApiCall:
   • Name: FetchWeatherData
   • URL: https://api.openweathermap.org/data/2.5/weather
   • Method: GET
   • Parameters:
     • Key:q
       • Value: Cairo (You can change the city dynamically based on user input or a database).
       • Parameter Type: URL
       • ValueType: StaticValue (or dynamic if needed).
     • Key:appid
       • Value: YourOpenWeatherAPIKey (replace with your API key).
       • Parameter Type: URL
       • ValueType: StaticValue
   • ResultType: Object (because the response is expected to be a single JSON object).
   • ResultedFieldKey: Use this if you want to extract specific data from the response (e.g., main.temp for temperature).
3. Map the Response to Database Fields (Optional):
   • If you want to store the data in your database, use the Mapping section to map the response fields to database columns. For example:
     • Map the main.temp (temperature) field to a column in your database for weather data.
     • Map the weather[0].description field to another column for storing the weather description.
4. Execute the API Call:
   • After setting up, execute the API call to fetch the weather data for the selected city (Cairo in this case).
5. Expected Outcome:
   • If successful, the API call will return weather data in JSON format, and it will be displayed in the log. If you’ve set up database mapping, the data will also be saved in your database.

---

Summary of Examples for Your Documentation:

Example 1: Sending Data to Slack API (POST)

• Purpose: Send a message to a Slack channel.
• URL: https://hooks.slack.com/services/your-webhook-url
• Method: POST
• Parameters: JSON body with the message text.
• Expected Outcome: A message appears in the Slack channel.

Example 2: Fetching Data from OpenWeather API (GET)

• Purpose: Retrieve weather data for a city.
• URL: https://api.openweathermap.org/data/2.5/weather
• Method: GET
• Parameters: q (city), appid (API key).
• Expected Outcome: Weather data is fetched and displayed or stored.

---

These examples can be adapted for other APIs by adjusting the URL, parameters, and expected response structures. By following the same process, you can integrate with various APIs for sending or receiving data as needed.