The HTTP task provides a basic HTTP/RESTful client that allows you to call RESTful endpoints. It is provided automatically by Concord, and does not require any external dependencies.
RESTful endpoints are very commonly used and often expose an API to work with an application. The HTTP task allows you to invoke any exposed functionality in third party applications in your Concord project and therefore automate the interaction with these applications. This makes the HTTP task a very powerful tool to integrate Concord with applications that do not have a custom integration with Concord via a specific task.
The HTTP task executes RESTful requests using a HTTP GET
, PUT
, PATCH
,
POST
, or DELETE
method and returns HTTP response
objects. The response object can be stored in an out
parameter for later
usage.
The HTTP Task automatically follows redirect URLs for all methods if the response returns status code 301. To disable this feature, set the
followRedirects
task parameter tofalse
.
As with all tasks you can invoke the HTTP task with a short inline syntax or
the full task
syntax.
The simple inline syntax uses an expression with the http task and the
asString
method. It uses a HTTP GET
as a default request method and returns
the response as string.
- log: "${http.asString('https://api.example.com:port/path/test.txt')}"
The full syntax is preferred since it allows access to all features of the HTTP task:
- task: http
in:
method: GET
url: "https://api.example.com:port/path/endpoint"
response: string
out: response
- if: ${response.success}
then:
- log: "Response received: ${response.content}"
All parameters sorted in alphabetical order.
auth
: authentication used for secure endpoints, details in
the Authentication section;body
: the request body, details in Body;connectTimeout
: HTTP connection timeout in ms. Default value is 30000 ms;debug
: boolean, output the request and response data in the logs;followRedirects
: boolean, determines whether redirects should be handled automatically.
Default is true
. Allows automatic redirection for all methods
if not
explicitly set to false
;headers
: add additional headers, details in Headers;ignoreErrors
: boolean, instead of throwing exceptions on unauthorized requests,
return the result object with the error;method
: HTTP request method, either POST
, PUT
, PATCH
, GET
, or
DELETE
. Default value is GET
;out
: variable to store the HTTP response object;proxy
: HTTP(s) proxy to use (see the example);query
: request query parameters, details in Query Parameter;request
: type of request data string
, json
, or file
, details available
in Request type;requestTimeout
: request timeout in ms, which is the maximum time spent
waiting for the response;response
: type of response data string
, json
, or file
received from
the endpoint, details in Response type;socketTimeout
: socket timeout in ms, which is the maximum time of inactivity
between two data packets. Default value is -1
, which means that the default
value of the Java Runtime Environment running the process is used - common value
is 60000 ms;url
: complete URL in string for HTTP request;The auth
parameter is optional. When used, it must contain the basic
nested
element which contains either the token
element, or the username
and
password
elements.
Basic auth using token
syntax:
auth:
basic:
token: value
In this case, the value
is used as Basic authentication token in the Authorization
header:
Authorization: Basic value
Basic auth using username
and password
syntax:
auth:
basic:
username: any_username
password: any_password
In this example, username
and password
values will be formatted according
to standard basic authentication rules:
Authorization: Basic base64(username + ":" + password)
To avoid exposing credentials in your Concord file, replace the actual values with usage of the Crypto task.
Use valid values for basic authentication parameters. Authentication failure
causes an UnauthorizedException
error.
The HTTP method type POST
, PUT
and PATCH
requires a body
parameter that
contains a complex object (map), json sourced from a file, or raw string.
Body for request type json
:
request: json
body:
myObject:
nestedVar: 123
The HTTP task converts complex objects like the above into a string and passes
it into the body of the request. The converted string for the above example is
{ "myObject": { "nestedVar": 123 } }
.
The HTTP task accepts raw JSON string, and throws an incompatible request
type
error when it detects improper formatting.
Body for Request Type file
:
request: file
body: "relative_path/file.bin"
Failure to find file of the name given in the referenced location results in
aFileNotFoundException
error.
Body for Request Type string
:
request: string
body: "sample string for body of post request"
Extra header values can be specified using headers
key:
headers:
MyHeader: "a value"
X-Some-Header: "..."
Query parameters can be specified using query
key:
query:
param: "Hello Concord"
otherParam: "..."
Parameters are automatically encoded and appended to the request URL.
A specific request type in request
is optional for GET
method usage, but
mandatory for POST
and PUT
. It maps over to the CONTENT-TYPE
header of the HTTP
request.
Types supported currently:
string
(converted into text/plain
)json
(converted into application/json
)file
(converted into application/octet-stream
)form
(converted into application/x-www-form-urlencoded
)formData
(converted into multipart/form-data
)response
is an optional parameter that maps to the ACCEPT
header of the HTTP
request.
Types supported currently:
string
(converted into text/plain
)json
(converted into application/json
)file
(converted into application/octet-stream
)Objects returned by the HTTP task contain the following fields:
success
: true if status code belongs to success familycontent
: json/string response or relative path (for response type file
)headers
: key-value pairs of response headersstatusCode
: http status codeserrorString
: Descriptive error message from endpointFollowing are examples that illustrate the syntax usage for the HTTP task.
- task: http
in:
method: GET # or DELETE
url: "https://api.example.com:port/path/endpoint"
response: json
out: jsonResponse
- if: ${jsonResponse.success}
then:
- log: "Response received: ${jsonResponse.content}"
Using a YAML object for the body:
- task: http
in:
request: json
method: POST # or PATCH or PUT
url: "https://api.example.com:port/path/endpoint"
body:
userObj:
name: concord
response: json
out: jsonResponse
- if: ${jsonResponse.success}
then:
- log: "Response received: ${jsonResponse.content}"
Using raw JSON for the body:
- task: http
in:
request: json
method: POST # `PATCH`, `PUT`
url: "https://api.example.com:port/path/endpoint"
body: |
{
"myObject": {
"nestedVar": 123
}
}
response: json
out: jsonResponse
- if: ${jsonResponse.success}
then:
- log: "Response received: ${jsonResponse.content}"
Using multipart form for the body
- task: http
in:
request: formData
method: POST
url: "https://api.example.com:port/path/endpoint"
body:
field1: "string value" # text/plain part
field2: "@myFile.txt" # application/octet-stream part with a filename
field3:
type: "text/plain" # manually specify the content-type of the part
data: "string value"
Using Basic Authentication with an existing value:
- task: http
in:
auth:
basic:
token: base64_encoded_token
method: GET
url: "https://api.example.com:port/path/endpoint"
response: json
out: jsonResponse
- if: ${jsonResponse.success}
then:
- log: "Response received: ${jsonResponse.content}"
Using Basic Authentication with a username and a password:
- task: http
in:
auth:
basic:
username: username
password: password
method: GET
url: "https://api.example.com:port/path/endpoint"
response: json
out: jsonResponse
- if: ${jsonResponse.success}
then:
- log: "Response received: ${jsonResponse.content}"
- task: http
in:
method: GET
url: "https://api.example.com:port/path/endpoint"
proxy: "http://proxy.example.com:8080"