A command line .http file toolkit
Warning
Zap is in early development and is not yet ready for use
zap is a command line toolkit to work with, execute, and run API tests using .http files. See any of the following guides for an overview of the .http file syntax:
// Comments can begin with slashes '/' or hashes '#' and last until the next newline character '\n'
# This is also a comment (I'll use '/' from now on but you are free to use both)
// Global variables (e.g. base url) can be defined with '@ident = <value>'
@base = https://api.company.com
// 3 '#' in a row mark a new HTTP request, with an optional comment e.g. "Deletes employee 1"
// This comment is effectively the description of the request
### [comment]
HTTP_METHOD <url>
Header-Name: <header value>
// You can also give them names like this, although names like this
// do not allow spaces e.g. 'Delete employee 1' must be 'DeleteEmployee1'
###
# @name <name>
# @name=<name>
# @name = <name>
HTTP_METHOD <url>
...
// Global variables are interpolated like this
### Get employee 1
GET {{ base }}/employees/1
// Pass the body of requests like this
### Update employee 1 name
PATCH {{ base }}/employees/1
Content-Type: application/json
{
"name": "Namey McNamerson"
}Compiled binaries for all supported platforms can be found in the GitHub release. There is also a homebrew tap:
brew install --cask FollowTheProcess/tap/zapGiven a .http file containing 1 or more http requests like this:
// demo.http
@base = https://jsonplaceholder.typicode.com
### Simple demo request
# @name Demo
GET {{ base }}/todos/1
Accept: application/jsonYou can invoke any one of them, like this...
# zap do [file] [request name]
zap do ./demo.http DemoWhile there is a strict specification for the format of pure HTTP requests (RFC9110). There is little/no formal specification for the evolution of the format used in this project, the closest things available are:
And careful inspection of them reveals a number of discrepancies and inconsistencies between them. As a result, knowing which features/syntax to support for this project was... tricky. So this project is a best effort to support the syntax and features that I thought was most reasonable and achievable in a standalone command line tool not built into an IDE.
Some of the more prominent differences are:
The JetBrains HTTP Request in Editor Spec specifies exact whitespace requirements between different sections e.g. a single \n character must follow a request line.
See https://github.com/JetBrains/http-request-in-editor-spec/blob/master/spec.md#23-whitespaces
This project makes no such requirement, whitespace is entirely ignored meaning the formatting of .http files is up to convention and/or automatic formatting tools
The JetBrains HTTP Request in Editor Spec allows for custom JavaScript Response Handlers (e.g. the {% ... %} blocks), that take the response and transform it in some way:
GET http://example.com/auth
> {% client.global.set("auth", response.body.token); %}This is not supported in zap as it relies on editor-specific context and requires a JavaScript runtime.
However, the version of this syntax where you dump the response body to a file is supported!
GET http://example.com/auth
> ./response.jsonThe JetBrains HTTP Request in Editor Spec allows for a Response Reference, but doesn't actually explain what that is or what should be done with it? So I've left it out for now 🤷🏻
GET http://example.com
<> previous-response.200.jsonNote
I can foresee a potential use for this syntax: Saving the first response to the filepath indicated and then the next time it runs, comparing the responses and generating a diff of the previous response vs the current one. This isn't implemented yet but it's in the back of my mind for the future 👀
This package was created with copier and the FollowTheProcess/go-template project template.