Ask AI
Skip to main content

API call

Function: API call​

Effortlessly connect and retrieve data from external systems using their Application Programming Interfaces (APIs). This function simplifies data integration and enhances your applications by allowing you to interact with various services without writing any code. You can use it for any REST API call that returns data in JSON or plain text format.

Input​

  • Authentication method (SELECT_ONE, Required, Default: None) Specify how you want to prove your identity to the API.
    • Basic authentication: A simple method where you provide a username and password.
    • Bearer Token: A security token passed in the request to grant access.
    • Api Token: A unique key that grants access to specific API features.
    • OAuth 1.0: A more complex method using signed requests with shared secrets and tokens.
    • None: No authentication will be used.
  • Username (STRING)
    • Only visible if "Authentication method" is "Basic authentication".
    • The username required for Basic authentication.
  • Password (PASSWORD)
    • Only visible if "Authentication method" is "Basic authentication".
    • The password required for Basic authentication.
  • Consumer Key (STRING)
    • Only visible if "Authentication method" is "OAuth 1.0".
    • The public identifier for your OAuth 1.0 client.
  • Consumer Secret (PASSWORD)
    • Only visible if "Authentication method" is "OAuth 1.0".
    • The private key associated with your Consumer Key, used to sign OAuth 1.0 requests.
  • Token ID (STRING)
    • Only visible if "Authentication method" is "OAuth 1.0".
    • The access token identifying the authorized user or account for OAuth 1.0 requests.
  • Token Secret (PASSWORD)
    • Only visible if "Authentication method" is "OAuth 1.0".
    • The secret associated with the access token, used to sign OAuth 1.0 requests.
  • Realm (STRING)
    • Only visible if "Authentication method" is "OAuth 1.0".
    • An optional identifier defining the protection space for OAuth 1.0 credentials.
  • Read timeout (NUMBER) The maximum time (in milliseconds) the system will wait for the entire response message to be received.
  • Connect timeout (NUMBER) The maximum time (in milliseconds) the system will wait for a connection to the API to be established.
  • Token (PASSWORD)
    • Only visible if "Authentication method" is "Bearer Token" or "Api Token".
    • The token used for Bearer or API Token authentication.
  • Headers (OBJECT) A collection of key-value pairs for custom HTTP headers to include in the API call (e.g., Content-Type: application/json).
  • Endpoint (STRING, Required) The complete URL of the API resource you want to access (e.g., https://api.example.com/data).
  • Query parameters (OBJECT) A collection of key-value pairs for parameters to append to the URL (e.g., ?id=123&category=books).
  • Method (SELECT_ONE, Required, Default: GET) The HTTP method to use for the API call.
    • GET: Retrieve data.
    • PUT: Update an existing resource entirely.
    • POST: Create a new resource.
    • DELETE: Remove a resource.
    • PATCH: Partially update an existing resource.
  • Request body (OBJECT)
    • Only visible if "Method" is "POST", "PUT", or "PATCH".
    • The data (as a key-value pair object) to send with the request, typically for creating or updating resources.
  • Response type (SELECT_ONE, Required, Default: JSON) Specify the format you expect the API's response to be in.
    • JSON: Structured data in JSON format.
    • Text: Plain text.
    • List: A list of items.

Output​

  • Response (VARIABLE, Default: RESPONSE) The name of the variable where the retrieved data from the API call will be stored. The content of this variable will be a Map, a List of Maps, or a String, depending on the chosen "Response type".
  • Response format (DATA_FORMAT) This allows you to define the expected structure of the API response, which can help in mapping the data to your application's data models.
  • Status (STATUS, Default: STATUS) The name of the variable where the outcome of the API call will be stored. Possible values include:
    • OK: The API call was successful.
    • BAD_REQUEST: Your request was invalid.
    • UNAUTHORIZED: You do not have sufficient authorization.
    • NOTFOUND: The specified endpoint could not be found.

Execution Flow​

Real-Life Examples​

Example 1: Fetching Public Weather Data​

Imagine you want to display the current weather for a city in your application using a public weather API that doesn't require authentication.

  • Inputs:
    • Authentication method: None
    • Endpoint: https://api.weatherapi.com/v1/current.json
    • Query parameters: \{"key": "YOUR_API_KEY", "q": "London"\}
    • Method: GET
    • Response type: JSON
    • Response variable name: CurrentWeather
    • Status variable name: WeatherAPIStatus
  • Result: The CurrentWeather variable will contain a JSON object with the current weather details for London (e.g., temperature, condition, humidity), and WeatherAPIStatus will be OK.

Example 2: Creating a New Task in a Project Management Tool​

You want to automatically create a new task in your project management system whenever a new customer request comes in. This API requires a Bearer Token for authentication.

  • Inputs:
    • Authentication method: Bearer Token
    • Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c (Replace with your actual token)
    • Endpoint: https://api.projecttool.com/tasks
    • Method: POST
    • Headers: \{"Content-Type": "application/json"\}
    • Request body: \{"title": "Follow up on new customer request", "description": "Contact customer X about their recent inquiry.", "dueDate": "2023-12-31"\}
    • Response type: JSON
    • Response variable name: NewTaskDetails
    • Status variable name: TaskCreationStatus
  • Result: A new task will be created in your project management tool. The NewTaskDetails variable will hold the details of the newly created task (e.g., its ID), and TaskCreationStatus will be OK.

Example 3: Updating a User's Email Address​

Your application needs to update a user's email address in an external user management system. This system uses Basic Authentication.

  • Inputs:
    • Authentication method: Basic authentication
    • Username: api_user
    • Password: secure_api_pass
    • Endpoint: https://api.usermanagement.com/users/456
    • Method: PATCH
    • Headers: \{"Content-Type": "application/json"\}
    • Request body: \{"email": "updated.email@example.com"\}
    • Response type: JSON
    • Response variable name: UserUpdateResult
    • Status variable name: UserUpdateStatus
  • Result: The user with ID 456 in the external system will have their email address updated. The UserUpdateResult variable will contain the updated user information, and UserUpdateStatus will be OK.