+++ title = "API Reference" weight = 2 +++
This document details the tasks used by Iris. Iris only has three tasks besides the standard vane tasks: %request, %cancel-request, and %receive. The %receive task is only sent to Iris by the runtime, so you're likely to only use %request and %cancel-request.
[%request =request:http =outbound-config]Fetch a remote HTTP resource.
The $request:http is the request itself and contains the HTTP method, the fully qualified target URL, a list of HTTP headers to be included and maybe the data for the body of the request.
The $outbound-config specifies the number of redirects to follow before failing and the number of retries to attempt before giving up. The default values are 5 and 3 respectively. As of writing, retries and auto-following redirects are not implemented, so what you specify here is irrelevant and you can just use the bunt value of outbound-config.
Iris returns a %http-response gift in response to a %request task. A %response gift looks like:
[%http-response =client-response]The $client-response contains the HTTP response from the server including the status code, HTTP headers and any data along with its mime type.
The client-response structure specifies three kinds of responses - %progress, %finished and %cancel. The %progress response would contain each chunk of the message as it came in, %finished would contain the final assembled message from Vere's buffer, and %cancel would be sent if the runtime cancels the request.
Note that neither %progress partial messages nor %cancel responses have been implemented in Vere at the time of writing, so you will only ever receive a single %http-response gift with a %finished client-response. If the request fails for some reason, you'll still get an empty %finished client-response with a 504 status code.
See the Example document.
[%cancel-request ~]Cancel a previous request to fetch a remote HTTP resource.
A %cancel-request task does not take any arguments, the request to cancel is determined implicitly.
Iris does not return any gift in response to a %cancel-request task. You will also not receive any gift back from the original %request task you've cancelled.
[%receive id=@ud =http-event:http]Receives HTTP data from outside. This task is sent to Iris by the runtime, you would not use it manually.
The id is a sequential ID for the event and the $http-event:http contains the HTTP headers and data.