api
Description
Makes requests to external APIs.
Syntax
api [<connection>] [<query>] [<url>] [<method>] [<verify>] [<ssl>] [<ssl_type>] [<cert>] [<auth>] [<auth_type>] [<params>] [<headers>] [<timeout>] [<body>] [<body_type>]
Optional Arguments
| Parameter | Syntax | Description |
|---|---|---|
connection | connection=<string> | Name of a predefined api connection. |
query | query=<string> | Name of a predefined api query. |
url | url=<string> | See URL Processing. |
method | <string> | HTTP request method, defaults to GET. |
verify | verify=<boolean> | When true, enables hostname verification. |
ssl | ssl=<boolean> | When true, enables ssl validation. |
ssl_type | ssl_type=<string> | ssl protocol type. Valid values: ssl2.3, ssl3, tls, tls1.1, tls1.2, tls1.3. |
cert | cert=<string> | Path to certificate when using ssl. |
auth | auth=<string> | Authorization token. |
auth_type | auth_type=<string> | Authorization type. Valid values: basic, apiKey, bearer. |
params | params=<string> | Request parameters. |
headers | headers=<string> | Request headers. |
timeout | timeout=<int> | Request timeout. |
body | body=<string> | Request body. |
body_type | body_type=<string> | body type. Valid values: json, xml, javascript, html, text, binary. |
The command requires either a url definition in the connection or a url argument to be specified.
When using both api connection or query and optional parameters, the optional parameters take precedence.
URL Processing
The final URL is constructed by processing URLs from connection and query arguments. If query contains a full URL, it's used as-is. For relative URLs, only the host value is taken from connection and combined with the path from query
If the url argument is provided. Its value overrides the URL from query. The same processing rules apply: full URLs are used as-is, while relative paths are combined with the host from connection.
Tokenization of params and headers
When using params and headers arguments, you can utilize tokens from the keystore.
Tokens for headers must be stored in the keystore under the path sme.sa.api.header.<token_name>, while tokens for params should be stored under sme.sa.api.param.<token_name>. Replace <token_name> with your actual token name, e.g., my_authorization.
Creating a token
To create a token of type header named my_authorization, make a request to the keystore. The value field should contain the actual value that will replace the token in requests.
POST _core/keystore/sme.sa.api.header.my_authorization
{
"value": "Basic "
}
Using tokens
To use tokens in the api command within search queries, specify the token name in double curly braces.
| api connection=my-connection headers="Authorization={{my_authorization}}"
Request Examples
Example 1
Queries the api specified in the url parameter and returns documents containing user information.
| api url="https://jsonplaceholder.typicode.com/users"
Example 2
The json connection contains the base URL https://jsonplaceholder.typicode.com/, which is combined with the resource path from the url parameter.
| api connection=json url="/todos"
Example 3
Executes a request using predefined api connection and query.
| api connection=my-connection query=my-query
Example 4
Executes a request using predefined api connection and query, but with ssl validation disabled.
| api connection=my-connection query=my-query ssl=false