Defining request templates

Request templates are a core part of hit. Request templates are a “functional” approach to APIs. In this guide, we will go over how to create and use request templates.

Basics

At its core, templates allow for injection of dynamic values into a request. A template provides a structure of a request and places where variable-based substitution can be performed.

Please make sure that no .hit files are present in your current working directory. Create a new directory if necessary.

Let’s start with a basic request:

echo '
@_global
base_url=https://nodes.yolo42.com
version=1


@gen-root-node
POST
/v1/node
~y2j
title: root-node
' > quick-start.hit

@gen-root-node defines a POST request. The body format is y2j meaning the request is defined as a YAML document in the hit file, and it is sent as JSON in the HTTP request. The title here is hard-coded to ‘root-node’. Let’s make it dynamic by introducing a variable.

echo '
@_global
base_url=https://nodes.yolo42.com
version=1


@gen-root-node
POST
/v1/node
~hy2j
title: "@2"
' > quick-start.hit

Two things have changed:

  • The body format has changed from y2j to hy2j. This instructs hit to perform a variable resolution. When the body format is y2j, hit does not perform any variable resolution.
  • The value of title key in the body has changed from root-node to @2. The numeric value 2 indicates that the second argument from the command-line should be used as the value. The CLI arguments are 0-indexed. The zeroth argument is hit - the program name, the first is the request ID which is @gen-root-node in this case and the second is what we will pass.

Let’s execute the request:

hit @gen-root-node foobar

Observe how the request body (as well as the response) has foobar as the title.

Multiple input values

You can input multiple values using the CLI as well.

Let’s take another example:

echo '
@_global
base_url=https://nodes.yolo42.com
version=1


@gen-root-node
POST
/v1/node
~hy2j
title: "@2"

@create-node
POST
/v1/node
~hy2j
title: "@2"
parent_id: "@3"
' > quick-start.hit

Here the @create-node request takes two inputs - a title and a parent_id.

Generate a root node:

hit @gen-root-node "Todo list"

Copy the id from the reponse and then create another node:

hit @create-node "Buy milk" "<id from previous request>"

Dynamic injection from cache

Copying output of a request and pasting it into a command is quite unwieldy. To make this easy, hit has caching of responses and referencing responses from templates as well as on the command line. This allows to quickly execute complex series of requests. To learn more, please follow the Using cached responses guide.