Skip to main content

Command Line Interface

The terminal or command line interface / CLI processes commands to a machine in the form of lines of text, as opposed to a graphical user interface. In this tutorial, we'll explain how to use cURL and HTTPie to interact with the PathLit API engine.

Pre-Requisite#

  • A PathLit account with an API Key (or token). Don't have one yet? get it here. The API key is a string looking like 56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS

  • PathLit base url: https://engine.pathlit.io/v1/

  • Two methods to call: we'll use timeseries/infos and optimiser/weights

cURL#

cURL is bundled with macOS, runs on Windows and Linux, and is used as a language-agnostic example in the documentation of countless APIs (including this one). In short, "cURL is a command-line tool for getting or sending data including files using URL syntax" wikipedia

Reading from the API [aka GET]#

PathLit requires the key to be passed in a header x-api-key. A simple example of a GET call with no parameters would be like:


curl \--request GET 'https://engine.pathlit.io/v1/timeseries/info' \--header 'x-api-key: 56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS'

Once the call is executed, the terminal will display the response sent by the server.

This is a bit hard to read though. We can 'beautify' this by using a binary called jq to format it in a more readable fashion (jq does not come with MacOS nor Windows or Linux, you will need to install it). We'll 'pipe' the output of cURL to jq

curl \--request GET 'https://engine.pathlit.io/v1/timeseries/info' \--header 'x-api-key: 56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS' \| jq

Saving the output to a file#

For MacOS/Linux/Unix users, you can simply do a redirection to a file. The API response is always a JSON format. For example saving our GET to a file named supported_tickers which we want to locate in the /var/tmp/ directory of our system, we just need to append the call with > '/var/tmp/supported_tickers.json'


curl \--request GET 'https://engine.pathlit.io/v1/timeseries/info' \--header 'x-api-key: 56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS' \| jq > '/var/tmp/curl_supported_tickers.json'

Sending computation to the API [aka POST]#

Let's send three instruments to the weights endpoint. We will received a json formatted response with all the possible strategies for this specific bucket (more on the weights endpoint).


curl \--request POST 'https://engine.pathlit.io/v1/optimiser/weights' \--header 'x-api-key: 56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS' \--header 'Content-Type: application/json' \--data-raw '{    "tickers": [        "AAPL",        "HOG",        "KO"    ]}'

In this case, we are using a POST action and we need to provide a payload: the three ticker symbols we would like to work on.

We are providing them in a json format with the --data-raw flag:

{    "tickers": [        "AAPL",        "HOG",        "KO"    ]}

Adding more ticker symbols is as easy as appending the list:

{    "tickers": [        "AAPL",        "HOG",        "KO",        "NVDA"    ]}

Like for our GET example, the request can be beautified by piping | the command to the jq utility. Saving the request into a file follows the same logic using the > /path/to/disk mechanism.

HTTPie#

HTTPie is a modern evolution of cURL, self described as the "user-friendly command-line HTTP client for the API era". Open source, detailed instructions are available at https://httpie.io/

Reading from the API [aka GET]#

Our GET example with HTTPie would look like this:

https  --follow --timeout 3600 GET 'https://engine.pathlit.io/v1/timeseries/info' \ x-api-key:'56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS'

The API engine will respond with a 200 OK HTTP code.

HTTP/1.1 200 OKConnection: keep-aliveContent-Length: 819Content-Type: application/jsonDate: Tue, 06 Apr 2021 03:28:33 GMT...

Here we are passing two optional flags --follow and --timeout 3600. The call perfectly works without this. HTTPie provides users with the ability to fine tune their requests. All the flags are explained in the documentation

Saving the output to a file#

For MacOS/Linux/Unix users, you can simply do a redirection to a file. The API response is always a JSON format. For example saving our GET to a file named supported_tickers which we want to locate in the /var/tmp/ directory of our system, we just need to append the call with '> /var/tmp/supported_tickers.json'

https  --follow --timeout 3600 GET 'https://engine.pathlit.io/v1/timeseries/info' \ x-api-key:'56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS' > '/var/tmp/supported_tickers.json'`

Sending computation to the API [aka POST]#

Sending a payload with HTTPie is somewhat similar to cURL. Because we are sending a custom json we need to pass it inline via a pipe | to our endpoint:

echo '{    "tickers": [        "AAPL",        "HOG",        "KO"    ]}'| https -f POST 'https://engine.pathlit.io/v1/optimiser/weights' x-api-key:'56IvxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxzLS'

The response is already nicely formatted, there is no need to pipe it to the jq utility. Here we use the shell echo command (MacOS, Linux, Unix) but we could have used printf. Having the output written in a file is exactly the same as with a GET.