GenericAPICall

Integration version of the httpv2 automation used to send HTTP requests for API calls to endpoints not associated with an existing XSOAR integration.

Utilities · Generic API Call

Details

ID	`GenericAPICall`
Provider	Open Source
Category	Utilities
From Version	5.5.0
Docker Image	`demisto/python3:3.12.13.10404775`
Supported Modules	Agentix XSIAM Cloud Posture Security

README

GenericAPICall Integration

This integration provides a method for executing HTTP API calls to specific API endpoints used in one-off scenarios not covered by other XSOAR integrations. This integration supports unauthenticated and authenticated API calls over HTTPS, using API key and basic HTTP authentication methods.

Configuration Parameters

Name - Integration instance name
Base Server URL - The base server URL for the API endpoint without the trailing slash (/)
Username - Username for HTTP basic authentication.
- Leave blank when using an API key
Password/API Key - The password (when using HTTP basic authentication) or API key to use for API calls with this integration instance
API call is authenticated - Check this box if API calls to this endpoint require authentication (Default: False)
API key supplied in header - Check this box if API key or authentication credentials are provided as part of the HTTP header (Default: False)
- Unchecking this box will pass the API key as a parameter in the URL (&apiKey=KEY_HERE)
Authentication Header - The value to use to identify the API key field as part of the HTTP header or API Key parameter in the URL
- Header example: { ‘AUTHENICATION_HEADER_HERE’: ‘API_KEY_HERE’ }
- Parameterized example: &AUTHENTICATION_HEADER=API_KEY_HERE
Use system proxy settings - Leverage the proxy settings configured on the XSOAR server
Trust any certificate (not secure) - Bypass SSL certificate verification for these connections

Commands

Execute a HTTP-based API call to the configured API endpoint

generic-api-call

Performs a HTTP-based API call to the server configured server and url path.
NOTE: Because of the potentially large amount of data returned per specific API call, no content is output to the war room except a message confirming call execution.

Base Command

!generic-api-call

Input

Argument Name	Description	Required
method	The HTTP method to use for the API call. (Default: POST) GET, POST, PUT, PATCH, DELETE, HEAD	Required
urlpath	The URL path to the API endpoint to be appended to the base_url parameter. (Default: /)	Required
parse_response_as	Specify the type of data expected in the API response Defined types: - json - raw_response - text - xml	Required
body	The body to be used for the API call	Optional
request_content_type	Specify the *Content-Type* header for the request.Shorthands are provided for the following common content types:json (application/json)xml (text/xml)form (application/x-www-form-urlencoded)data (multipart/form-data). If you choose to define a different type, please include the full type name, e.g: *application/pdf* Predefined types: - application/json - application/pdf - application/x-www-form-urlencoded - application/xml - multipart/form-data - text/csv - text/plain - text/xml	Optional
response_content_type	Specify the *Accept* header for the request.Shorthands are provided for the following common content types:json (application/json)xml (text/xml)form (application/x-www-form-urlencoded)data (multipart/form-data). If you choose to define a different type, please include the full type name, e.g: *application/pdf* Predefined types: - application/json - application/pdf - application/x-www-form-urlencoded - application/xml - multipart/form-data - text/csv - text/plain - text/xml	Optional
params	User-defined parameters for the API call	Optional
save_as_file	Save the API response as a file to context in XSOAR (Default: False)	Optional
file_name	The filename to save the returned API response as in XSOAR (Default: http-file)	Optional
timeout	Specify the timeout of the HTTP request in seconds. (Default: 10 seconds)	Optional
timeout_between_retries	Specify the timeout between each retry in seconds. (Default: 5 seconds)	Optional
retry_count	Specify the number or retries to be made in case of a call failure. (Default: 3 attempts)	Optional
retry_on_status	Specify a list of HTTP status codes that a retry should be attempted on. For example: 301-303,400,402.”	Optional
enable_redirect	The request will be called again with the new URL (Default: false)	Optional

Context Output

The response data

Path	Type	Description
APICall.StatusCode	String	The HTTP status code returned from the request
APICall.StatusText	String	The text corresponding to the returned HTTP status code
APICall.URL	String	The URL of the API call
APICall.ParsedBody	String	The parsed response, formatted according to `parse_response_as` argument
APICall.Headers	String	The headers from the API call response
APICall.Body	String	The raw data returned from the API call

Command examples

All examples in this documentation are based off the following endpoints:

JSON: https[:]//api[.]apis[.]guru/v2/metrics.json
XML: https[:]//boardgamegeek[.]com/xmlapi/search?search=civilizations
JSON Request Body: https[:]//reqres[.]in/

Command example - JSON

API call with output to context - JSON Return

!generic-api-call urlpath=/metrics.json request_content_type=application/json response_content_type=application/json method=GET parse_response_as=json

Context Example

JSON Context Output - 1
JSON Context Output - 2

Human Readable Output

Sent a GET request to https://api.apis.guru/v2

Command example - XML

API call with output to context - XML Return

!generic-api-call urlpath=/xmlapi/search?search=civilizations method=GET request_content_type=application/xml response_content_type=application/xml parse_response_as=xml

Context Example

XML Context Output - 1
XML Context Output - 2
XML Context Output - 3

Human Readable Output

Sent a GET request to https://boardgamegeek.com/xmlapi

Command example - Saving output to file in war room/context

Saving output to file in context/war room

!generic-api-call urlpath=/metrics.json request_content_type=application/json response_content_type=application/json method=GET parse_response_as=json save_as_file=true

Context Example

File output - Context

Human Readable Output

File output - War Room

Command example - API Call with JSON Request Body

API call with output to context - JSON specified in request body

!generic-api-call response_content_type=application/json method=POST urlpath=/api/users parse_response_as=json body=`{"name": "xsoar", "job": "XSOAR Ninja"}` request_content_type=application/json

Output Example

JSON Request Body Output Example

Human Readable Output

Sent a POST request to https://reqres.in

Command example - ElasticSearch Cases API Call

As the current ElasticSearch integration does not support pulling case data, the Generic API Call integration can be used to perform such a data pull. In the below example, a generic API call is issued to pull back a list of cases in ElasticSearch tied to the Elastic Cases API. Below are screenshots showing how the integration is configured to authenticate to ElasticSearch.

Please make note of the way the API key and authorization header are specified. For the API key, Elastic uses the “Authorization” header with an API key formatted as “ApiKey ENCODED_KEY_HERE”. The “ApiKey ENCODED_KEY_HERE” text goes in the password field for the integration, while “Authorization” is specified in the “Authentication Header” integration instance configuration field. The USERNAME field is left blank in the integration configuration for a call to the ElasticSearch API endpoint.

GenericAPICall Integration Configuration for ElasticSearch Cases

API call with output to context - ElasticSearch Cases API

!generic-api-call method=GET parse_response_as=json enable_redirect=true urlpath=/_find"

Context Example

Elastic Generic API Call Context Output

Human Readable Output

Sent a GET request to https://X.X.X.X/api/cases

Configuration parameters

base_url — Base API Endpoint URL (https:// with no trailing slash) (required)
credentials — Username (Blank when using API key)
is_auth — API call is authenticated (Default: False)
apikey_in_header — API Key supplied in header
api_call_key — Authentication Header
proxy — Use system proxy settings
insecure — Trust any certificate (not secure)

Commands (1)

generic-api-call
Generic HTTPS request to a specified API endpoint.

Source

GenericAPICall.py GenericAPICall.yml GenericAPICall_description.md

Download History Raw

category: Utilities
provider: Open Source
sectionorder:
- Connect
commonfields:
  id: GenericAPICall
  version: -1
configuration:
- name: base_url
  display: Base API Endpoint URL (https:// with no trailing slash)
  required: true
  type: 0
  section: Connect
- name: credentials
  display: Username (Blank when using API key)
  required: false
  type: 9
  additionalinfo: >-
    For basic authorization, specify both username and password or select the
    appropriate credential object.


    For API key authorization, fill in the password field only or use only the password field in a credential object. 
  displaypassword: Password/API Key
  section: Connect
- name: is_auth
  display: "API call is authenticated (Default: False)"
  required: false
  defaultvalue: "false"
  type: 8
  section: Connect
  additionalinfo: Does this API call require authentication (Basic, API key, etc.)?
- name: apikey_in_header
  display: API Key supplied in header
  required: false
  defaultvalue: "false"
  type: 8
  section: Connect
  additionalinfo: >-
    Is the API key used for each call provided in the header or as a
    parameter?

    Default it set to false (key is provided as a parameter). Unchecking this will pass the API key as a call header
- name: api_call_key
  display: Authentication Header
  required: false
  type: 0
  section: Connect
  additionalinfo: >-
    Specify the value to use when passing the API key as a header or parameter
    value.

    e.g., X-PAN-KEY: API_KEY_HERE (X-PAN-KEY is the value specified in this field) 

    - For a parameterized call, this would be appended to the URL as &X-PAN-KEY=KEY_HERE - 

    - For a header-based call, this would appear in the header as 'X-PAN-KEY': KEY_HERE
- name: proxy
  display: Use system proxy settings
  required: false
  defaultvalue: "false"
  type: 8
  section: Connect
  advanced: true
- name: insecure
  display: Trust any certificate (not secure)
  required: false
  defaultvalue: "false"
  type: 8
  section: Connect
  advanced: true
description: Integration version of the httpv2 automation used to send HTTP requests for API calls to endpoints not associated with an existing XSOAR integration.
display: GenericAPICall
name: GenericAPICall
script:
  commands:
  - name: generic-api-call
    description: Generic HTTPS request to a specified API endpoint.
    arguments:
    - name: method
      description: Specify the HTTP method to use (GET, POST, PUT, PATCH, DELETE, HEAD).
      auto: PREDEFINED
      required: true
      predefined:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE
      - HEAD
    - name: urlpath
      description: The URL path, including preceeding slash, to the API endpoint.
      required: true
      defaultValue: /
    - name: parse_response_as
      description: Specify the type of data expected in the API response.
      required: true
      auto: PREDEFINED
      predefined:
      - json
      - text
      - xml
      - raw_response
    - name: body
      description: Specify the body of the request.
    - name: request_content_type
      description: "Specify the Content-Type header for the request.Shorthands are provided for the following common content types:json (application/json)xml (text/xml)form (application/x-www-form-urlencoded)data (multipart/form-data)If you choose to define a different type, please include the full type name, e.g: application/pdf."
      auto: PREDEFINED
      predefined:
      - application/json
      - application/pdf
      - application/x-www-form-urlencoded
      - application/xml
      - multipart/form-data
      - text/csv
      - text/plain
      - text/xml
    - name: response_content_type
      description: "Specify the Accept header for the request - the response content type.Shorthands are provided for the following common content types:json (application/json)xml (text/xml)form (application/x-www-form-urlencoded)data (multipart/form-data)If you choose to define a different type, please include the full type name, e.g: application/pdf."
      auto: PREDEFINED
      predefined:
      - application/json
      - application/pdf
      - application/x-www-form-urlencoded
      - application/xml
      - multipart/form-data
      - text/csv
      - text/plain
      - text/xml
    - name: params
      description: URL parameters to specify the query.
    - name: save_as_file
      description: "Save the response in a file (Default: false)."
      defaultValue: "false"
      auto: PREDEFINED
      predefined:
      - 'true'
      - 'false'
    - name: file_name
      description: Name of file to save response as.
    - name: timeout
      description: Specify the timeout of the HTTP request in seconds. Defaults to 10. seconds.
      defaultValue: "10"
    - name: timeout_between_retries
      description: Specify the timeout between each retry in seconds. Defaults to 5.
      defaultValue: "5"
    - name: retry_count
      description: Specify the number or retries to be made in case of a failure. Defaults to 3.
      defaultValue: "3"
    - name: retry_on_status
      description: "Specify the array of status codes that should cause a retry. For example: 301-303,400,402."
    - name: enable_redirect
      description: "The request will be called again with the new URL (Default: false)."
      defaultValue: "false"
      auto: PREDEFINED
      predefined:
      - 'true'
      - 'false'
    outputs:
    - contextPath: APICall.StatusCode
      description: The number that indicates the status of the request.
      type: String
    - contextPath: APICall.StatusText
      description: The text corresponding to the status code.
      type: String
    - contextPath: APICall.URL
      description: The URL of the API call.
      type: String
    - contextPath: APICall.ParsedBody
      description: The parsed response, formatted according to `parse_response_as` argument.
      type: String
    - contextPath: APICall.Headers
      description: The response headers.
      type: String
    - contextPath: APICall.Body
      description: The response data.
      type: String
  runonce: false
  script: ''
  type: python
  subtype: python3
  dockerimage: demisto/python3:3.12.13.10404775
fromversion: 5.5.0
tests:
- No tests (auto formatted)