🌐 Zapman (alpha)

An API Client for the terminal. A Python CLI for API testing and development.

usage: zap [-h] {run,curl,cookies,vars,version} ...

An API Client for the terminal. A Python CLI for API testing and development.

options:
  -h, --help            show this help message and exit

commands:
  {run,curl,cookies,vars,version}
    run                 🚀 run a Zapfile
    curl                🌊 print the curl command for a Zapfile
    cookies             🍪 view stored cookies
    vars                📋 view stored variables
    version             🔖 show version

💡 Rationale

I've mainly built this tool to have a simple way to define and share collections of HTTP requests. I mainly work in the terminal, ideally I can manage everything from within an IDE (in my case VSCode). I've used Postman in the past and I've always found it a bit too heavy for my needs.

I wanted something that was simple to use, scriptable, and shareable. I also wanted to use a language that I know well, Python. Something that provides a CLI and just works in the terminal.

Zapman has been built on top of HTTPie, which is a great tool for making HTTP requests. I've also added some features that I found useful, like environments and variables, and the ability to capture output and store state. I've also made it easy to share collections by tracking them in a github repo. I hope you find this tool useful!

✨ Features

• 🐍 Define requests with pure python
• 🛠️ Environments & variables
• 🔄 Scriptable: parse responses, update environment variables, etc.
• 🚀 Collaborate and share via Git (they’re just Python files 🤷🏽‍♀️)
• 🖥️ Lightweight and simple CLI
• 🌈 Beautiful & colored output

🚀 Using

To install this package, run:

pip install zapman

GET request

Create a Zapfile called get.py:

GET = "https://httpbin.org/get"

PARAMS = {
    "foo": "bar"
}

Run with:

zap run get.py

Output:

GET /get?foo=bar HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: httpbin.org
User-Agent: Zapman/0.0.0



HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 325
Content-Type: application/json
Date: Thu, 19 Dec 2024 23:26:56 GMT
Server: gunicorn/19.9.0

{
    "args": {
        "foo": "bar"
    },
    "headers": {
        "Accept": "*/*",
        "Accept-Encoding": "gzip, deflate",
        "Host": "httpbin.org",
        "User-Agent": "Zapman/0.0.0",
        "X-Amzn-Trace-Id": "Root=1-6764abbf-60e6ac856a6fe7c32c0e2f3b"
    },
    "origin": "0.0.0.0",
    "url": "https://httpbin.org/get?foo=bar"
}


Elapsed time: 1.10440575s

POST request

Create a Zapfile called post.py:

POST = "https://httpbin.org/post"

BODY_FORM = {
    "foo": "bar"
}

Run with:

zap run post.py

Output:

POST /post HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 7
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: httpbin.org
User-Agent: Zapman/0.0.1

foo=bar


HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 482
Content-Type: application/json
Date: Sat, 21 Dec 2024 13:54:44 GMT
Server: gunicorn/19.9.0

{
    "args": {},
    "data": "",
    "files": {},
    "form": {
        "foo": "bar"
    },
    "headers": {
        "Accept": "*/*",
        "Accept-Encoding": "gzip, deflate",
        "Content-Length": "7",
        "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
        "Host": "httpbin.org",
        "User-Agent": "Zapman/0.0.1",
        "X-Amzn-Trace-Id": "Root=1-6766c8a4-19b2d0c813b7161f02cc4b30"
    },
    "json": null,
    "origin": "0.0.0.0",
    "url": "https://httpbin.org/post"
}


Elapsed time: 0.479004791s

Print cURL command

Create a Zapfile called put_json.py:

PUT = "https://httpbin.org/put"

HEADERS = {
    "X-Dude": "Duderino",
}

BODY_JSON = {
    "name": "Jeffrey",
    "last_name": "Lebowski",
}

Run with:

zap curl put_json.py

Output:

curl -i -X PUT 'https://httpbin.org/put' \
--header 'X-Dude: Duderino' \
--header 'Content-Type: application/json' \
--data '{"name": "Jeffrey", "last_name": "Lebowski"}'

Use environment & store environment variables

Create an "environments" file called zapenvs.py:

def env_default() -> dict[str, str]:
    """Provide default environment."""
    return {
        "endpoint": "https://httpbin.org",
    }

Create a Zapfile called store.py:

from zapman import After, env

GET = f"{env['endpoint']}/get"

PARAMS = {
    "foo": "bar",
}


def after(ctx: After) -> None:
    env["my_var"] = ctx.json["args"]
    env["my_date"] = ctx.headers["Date"]

Run with:

zap run --quiet store.py
zap vars

Output:

Environment: default
  my_var={'foo': 'bar'}
  my_date=Sat, 21 Dec 2024 22:57:38 GMT

More examples

More example Zapfiles can be found in zaps. Dive deeper into how to use environments, environment variables, and cookies.

🧑‍💻 Contributing

Prerequisites

1. Install Docker

1. Go to Docker, download and install docker.
2. Configure Docker to use the BuildKit build system. On macOS and Windows, BuildKit is enabled by default in Docker Desktop.

2. Install VS Code

Go to VS Code, download and install VS Code.

1. Open DevContainer with VS Code

Open this repository with VS Code, and run Ctrl/⌘ + ⇧ + P → Dev Containers: Reopen in Container.

The following commands can be used inside a DevContainer.

2. Run linters

poe lint

3. Run tests

poe test

4. Update poetry lock file

poetry lock --no-update

---

See how to develop with PyCharm or any other IDE.

---

️⚡️ Scaffolded with Poetry Copier.
🛠️ Open an issue if you have any questions or suggestions.