:imagesdir: doc ifdef::env-github[] :imagesdir: https://raw.githubusercontent.com/Leopard2A5/fhttp/master/doc endif::[]

:toc:

image::logo.png[] image:https://github.com/Leopard2A5/fhttp/workflows/.github/workflows/test.yml/badge.svg[] image:https://img.shields.io/twitter/follow/fhttp_tool?style=social[link=https://twitter.com/fhttp_tool]

== What's this? The file-based command line http client.

FHTTP is not a curl replacement. It’s meant to be a developers’ tool to make http requests and store them as files, usually in a source code repository along with an application accepting http requests. It’s inspired by tools like Postman, Insomnia and the IntelliJ http client.

|GUI |✕ |✕ |✓ |✓ |✕ |Request collections |✕* |✓ |✓ |✓ |✓ |Versioning |✕* |✓ |✕ |✕ |✓ |Scriptable |✓ |✓ |✕ |✕ |✕ |Env vars |✓ |✓ |✕ |✕ |✓ |Profiles |✕ |✓ |✓ |✓ |✕ |https://www.passwordstore.org/[Pass] secrets |✕* |✓ |✕ |✕ |✕ |https://1password.com/[1Password] secrets |✕* |✓ |✕ |✕ |✕ |Run multiple requests in one operation |✕ |✓ |✓ |✕ |✕ |Share collections |✕* |✓ |✓** |✕ |✓ |Full JavaScript response processing |✕ |✕ |✓ |✕ |✓ |Rhai response processing |✕ |✓ |✕ |✕ |✕ |Plugins |✕ |✕ |✕ |✓ |✕ |GraphQL schema autocompletion |✕ |✕ |✕ |✓ |✕

|=== $$*$$ available if you use CUrl with shell scripts

$$**$$ requires account

== Installation

There are multiple ways to install FHTTP:

through cargo (recommended, currently the only way to install for apple silicon) . run cargo install fhttp (note: on ubuntu you need the apt packages build-essential, pkg-config and libssl-dev)
homebrew . run brew tap Leopard2A5/fhttp && brew install fhttp
manually . download the latest version https://github.com/Leopard2A5/fhttp/releases[here] . rename the downloaded file? . make the file executable . make sure it’s on your PATH

Linux users: if you get

error while loading shared libraries: libssl.so.1.0.0: cannot open shared object file: No such file or directory

you need to install libssl1.0.0: sudo apt-get install libssl1.0.0

== Features

Simply author a request in a *.http file
Save a collection of requests right in your project repository
Use profiles to easily switch between environments
Resolve (environment) variables in your requests
Resolve secrets stored in https://www.passwordstore.org/[pass] or https://1password.com/[1Password]
Add dependencies between requests
Support for graphql requests
multipart file uploads
export to cURL command

== Anatomy of a request file === HTTP format A request file looks like this: [source]

METHOD URL HEADERS?

BODY?

RESPONSE_HANDLER?

The only mandatory parts are the method (get, post, patch, ...) and the url. You can prefix header lines with # to ignore that line.

Example request: [source]

POST https://oauth2tokenendpoint content-type: application/json; charset=UTF-8

{ "client_id": "foo", "client_secret": "bar" }

{% json $.access_token %}

JSON and YAML

Since version 1.6, FHTTP supports requests in json and yaml file formats. The main advantage of these formats is that they are well-known and that they allow you to create multipart requests with greater control. They are also the only way in FHTTP to mix file parts and form-data parts in a multipart request. The format and structure of the formats is the same.

YAML format is recommended because of JSON's verbosity and YAML's improved multiline string handling features.

.Graphql request

method: post
url: http://localhost/graphql
headers:
  authorization: Bearer ${request("token.http")}
  content-type: application/json
body: |
  {
    "query": "query($series: String!) { characters(series: $series) { name } }",
    "variables": {
      "series": "Breaking Bad"
    }
  }
response_handler:
  json: "$.data.characters"

.Multipart json request

{
    "method": "post",
    "url": "http://localhost/upload",
    "body": [
        {
            "name": "metadata",
            "text": "{ \"foo\": \"bar\" }",
            "mime": "application/json"
        },
        {
            "name": "file",
            "filepath": "image.png"
        }
    ]
}

As with *.http files, method and url are mandatory, while headers, body and response_handler are optional fields.

Note that json and yaml formats don't have a graphQL convenience function as *.gql.http requests do.

The body atttribute can either be a plain string or a list of objects to create a multipart request. Each object needs a name and either a text or filepath. Optionally you can force a content-type for that part via the mime attribute.

== Output FHTTP conveniently prints log messages to stderr and response bodies to stdout. For example:

> fhttp get-entities.http

[source]

fhttp request.http POST https://auth-server/token... 200 OK GET https://server/entities... 200 OK { "payload": 123 }

In this example get-entities.http has a dependency on another request to fetch an authentication token, which is executed first. FHTTP then preprocesses get-entities.http with the data from token.http and executes it, printing the result to stdout.

You can tell FHTTP to print the paths to the executed request files instead of methods and urls, by passing the -P or --print-paths flag. This is particularly useful when working with graphql servers that combine several queries and mutations under a single path (/graphql).

=== Verbose option By increasing the verbosity with the -v option, you can tell FHTTP to also log usage of secrets. This can be useful if FHTTP seems slow, because the secret lookup can take some time.

== How does it work?

image::process.png[]

When you invoke FHTTP, the following will happen:

find profile file, load default profile, load requested profile, if any
for every given request, find referenced requests, find best execution order
for every request . resolve variables . insert dependency results . send request . apply response handler, if any . save result . print result, unless this request is a dependency and the user didn't explicitly specify it when invoking FHTTP

== Request preprocessing You can use expressions in your request files. Expressions have the form ${expression}. The following table gives an overview of what's currently supported.

.Preprocessing expressions |=== | Expression | Description | Usable in

| ${env(NAME)} | Insert the environment variable NAME, or a profile variable with that name. If the variable is not found, FHTTP will prompt you for it, unless you've activated the --no-prompt option. | method, url, headers, body

| ${env(NAME, "default")} | Insert the environment variable NAME, or the given default value if the environment variable is not set. | method, url, headers, body

| ${randomInt(lower, upper)} | Insert a random integer. Lower and upper bounds are optional; you have to give a lower if you want to give an upper bound. | method, url, headers, body

| ${uuid()} | Insert a randomly generated UUID. | method, url, headers, body

| ${request("PATH")} | Insert the postprocessed body of the request file denoted by PATH. PATH can be absolute or relative to the location of the file containing the request(...) expression. | method, url, headers, body

| ${include("PATH")} | Insert the content of the file denoted by PATH. FHTTP will remove a single trailing newline character when including a file.

You can use all expressions inside included files, including include itself, this is especially useful when working with GraphQL fragments. | method, url, headers, body

| ${include_indent("PATH")} | like include, but preserve the indentation of the point of invocation in the included text. Particularly useful in yaml requests, where the normal include may invalidate the yaml document. | see ${include("PATH")}

| ${file("NAME", "PATH")} | Only supported in the body segment of a request. replaces all other body content except for other file(...) expressions. Use this to send a multipart request, uploading the given file(s). | body |===

Response handlers / postprocessing

Every request can contain a single response handler expression. To specify a response handler, leave an empty line after the body, then put the expression in > {% handler %}. For example:

[source]

POST http://localhost:8080

{ "foo": "bar" }

{% json $.path.inside.response %}

.Supported response handlers |=== | Handler | Description

| json | Accepts a https://support.smartbear.com/readyapi/docs/testing/jsonpath-reference.html[jsonpath] expression that is applied to the response body. | deno | *** Deno is no longer supported. *** | https://rhai.rs/[rhai] | Accepts a rhai script that can be used for complex checks and transformations of the response. |===

Rhai response handlers

In contrast to the other reponse handlers, a rhai script will be invoked even if the http status code of the response does not indicate success (200-299). This allows for more flexibility overall, but the script author is responsible for checking the status code.

The status code and the response body are passed into the script as status and body.

If the script returns a string, then that is used as the output of the response handler. If the script returns nothing, the original body of the response is used.

Consider the following response and the script to handle it.

Fhttp

Install / Use

README

== Anatomy of a request file === HTTP format A request file looks like this: [source]

RESPONSE_HANDLER?

Example request: [source]

JSON and YAML

[source]

Response handlers / postprocessing

[source]

Rhai response handlers