fc
fhttp-core
cargo install fhttp-core
fc

fhttp-core

core library for the fhttp tool

by René Perschon

1.3.1 (see all)License:MIT
cargo install fhttp-core
Readme

\= FHTTP
:toc:

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

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

FHTTP is not a curl replacement. It’s meant to be a developer’s 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.

\== Installation

There are multiple ways to install FHTTP:

* homebrew
. run `brew tap Leopard2A5/fhttp && brew install fhttp`
* through cargo
. run `cargo 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\]
* Add dependencies between requests
* Support for graphql requests
* multipart file uploads

\== Anatomy of a request file
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
%}
----

\== 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 pass secrets. This can be useful if FHTTP seems slow, because the pass lookup can take some time.

\== How does it work?

image::process.png[]

When you invoke FHTTP, the following will happen:

1. find profile file, load default profile, load requested profile, if any
2. for every given request, find referenced requests, find best execution order
3. 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, except `include` itself.
| method, url, headers, body

| `${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.

|===

## Profiles
You can create profiles to avoid having to provide variables manually every time you invoke FHTTP. Profiles allow you to easily switch the target environment of a request. By default, FHTTP will use a file called `fhttp-config.json` if present. A profile file could look like this:

[source,json]
----
{
"default": {
"variables": {
"URL": "http://localhost:8080"
}
},
"localhost": {
"variables": {
"token": "NO_AUTH"
}
},
"testing": {
"variables": {
"URL": "https://testing.myapp.com",
"CLIENT_ID": "clientid",
"CLIENT_SECRET": {
"pass": "path/to/clientsecret/in/passwordstore"
},
"token": {
"request": "get_token.http"
}
}
}
}
----

You can change which profile file to use by using the `--profile-file` option.

You can specify which profile to use with the `--profile` option. The default profile is always loaded if one is present and its values are overwritten by any other profile you specify.

Variables in profiles can have different forms:

.Profile variables
|===
| Variable | Description | Example

| String
| Sets the variable to this string.
a|
[source]
----
"var": "string"
----

| Pass secret
| Resolves the variable using the https://www.passwordstore.org/\[pass\] password store.
a|[source,json]
----
{
"pass": "path/in/pass"
}
----

| Request
| Resolve a request and use the postprocessed response body for the variable. Absolute path or relative from the location of the profile file.
a|
[source,json]
----
{
"request": "path/to/request/file"
}
----
|===

\== Graphql
GraphQL requests are transmitted to the server as json, so naively a
graphql request file would look like this:

[source]
----
POST http://graphqlserver
Content-Type: application/json

{
"query": "query($var1: String!) { foo(var1: $var1) { field1 } }",
"variables": {
"var1": "val1"
}
}
----

That's not very pretty, especially with longer graphql queries, as we need to escape line breaks in json. However, FHTTP supports graphql requests directly. Just change the file's extension to *.gql.http or *.graphql.http and change it like this:

[source]
----
POST http://graphqlserver

query($var1: String!) {
foo(var1: $var1) {
field1
}
}

{
"var1": "val1"
}
----

FHTTP automatically sets the content-type to application/json, escapes the query string and constructs the json payload with the query and variables. Response handlers are also supported in graphql requests. Graphql requests also support the full range of preprocessing expressions.

GitHub Stars

22

LAST COMMIT

9mos ago

MAINTAINERS

1

CONTRIBUTORS

2

OPEN ISSUES

2

OPEN PRs

0
VersionTagPublished
1.3.1
2yrs ago
1.3.0
2yrs ago
1.2.0
2yrs ago
1.1.0
2yrs ago
No alternatives found
No tutorials found
Add a tutorial