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