Request

An HTTP request starts with a request line followed by optional header fields, message body, response handler, and previous response references.

Request-Line

A request lineopen in new window consists of a request method, target and the HTTP protocol version. If the request method is omitted, ‘GET’ will be used as a default. The HTTP protocol version can be also omitted.

GET https://www.google.de HTTP/1.1

GET https://www.google.de
###
https://www.google.de

TIP

The HTTP version is optional. But in this guide I have always added it because of syntax highlighting

If the Http version is specified, this can be used to control the use of HTTP2

# no version = http/1.1
GET https://www.google.de

GET https://www.google.de HTTP/1.1

GET https://www.google.de HTTP/2.0

Allowed Requests Methods are:

GETPOSTPUTDELETEPATCH
OPTIONSCONNECTTRACEPROPFINDPROPPATCH
COPYMOVELOCKUNLOCKCHECKOUT
REPORTMERGEMKACTIVITYMKWORKSPACEVERSION-CONTROL

A request path can be added in the next line

GET https://httpbin.org
  /get

Query Strings

A request queryopen in new window may contain any unicode characters except line separators and the ‘#’ symbol.

@[code http](../../examples/request/queryString.http

It is also possible to split the query strings to different subsequent lines.

GET https://httpbin.org/anything
  ?q=httpyac
  &ie=UTF-8

Headers

Each header fieldopen in new window consists of a case-insensitive field name followed by a colon (‘:’), optional leading whitespace, the field value, and optional trailing whitespace.

GET https://httpbin.org/anything HTTP/1.1
Content-Type: text/html
Authorization: Bearer token

If you use the same headers several times, it is possible to store them in a variable and reuse them.

{{+
  const token = "test"
  exports.defaultHeaders = {
    'Content-Type': 'text/html',
    'Authorization': `Bearer ${token}`
  };
}}
###
GET https://httpbin.org/anything HTTP/1.1
...defaultHeaders
GET https://httpbin.org/anything HTTP/1.1
...defaultHeaders







 




CookieJaropen in new window support is enabled by default. All received Cookiesopen in new window, previously sent by the server with the Set-Cookie header are automatically sent back. It is possible to send own cookies to the server using cookie header.

GET https://httpbin.org/cookies HTTP/1.1
Cookie: bar=foo

WARNING

Cookies are only stored In-Memory and are cleared in VS Code with command httpyac.reset

It is possible to disable cookie support per request.

# @no-cookie-jar
GET https://www.google.de HTTP/1.1
 

Request Body

The request bodyopen in new window can be represented as a simple message or a mixed type message (multipart-form-data).

POST https://httpbin.org/anything HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

WARNING

The first content that is not recognized as a header or query string is interpreted as a request body. After that, no more header or query string can be specified.

Imported Request Body

A body can also be imported by using < ....

POST https://httpbin.org/anything HTTP/1.1
Content-Type: application/json

< ./requestBodyImport.json



 

If you want to replace variables in the file please import it with <@

@foo="bar"
POST https://httpbin.org/anything HTTP/1.1
Content-Type: application/json

<@ ./requestBodyImport.json




 

All files are read with UTF-8 encoding. If a different encoding is desired, provide it. All encodingsopen in new window supported by NodeJS are available.

@foo="bar"
POST https://httpbin.org/anything HTTP/1.1
Content-Type: application/json

<@latin1 ./requestBodyImport.json




 

WARNING

If the request body is configured in-place, whitespace around it will be trimmed. To send leading or trailing whitespace as part of the request body, send it from a separate file.

TIP

You can use Variable Substitution in file import.

@assetsDir=./
###

POST https://httpbin.org/anything HTTP/1.1
Content-Type: application/json

< {{assetsDir}}requestBodyImport.json






 

multipart/form-data

It is possible to mix inline text with file imports

POST https://httpbin.org/post HTTP/1.1
Content-Type: multipart/form-data; boundary=WebKitFormBoundary

--WebKitFormBoundary
Content-Disposition: form-data; name="text"

invoice_text
--WebKitFormBoundary
Content-Disposition: form-data; name="title"

invoice_title
--WebKitFormBoundary
Content-Disposition: form-data; name="invoice"; filename="invoice.pdf"
Content-Type: application/pdf

< ./dummy.pdf
--WebKitFormBoundary--

GraphQL

GraphQL queries are supported. Parsing Logic will automatically generate a GraphQL request body from the query and the optional variables.

POST https://api.spacex.land/graphql HTTP/1.1
Content-Type: application/json


query launchesQuery($limit: Int!){
  launchesPast(limit: $limit) {
    mission_name
    launch_date_local
    launch_site {
      site_name_long
    }
    rocket {
      rocket_name
      rocket_type
    }
    ships {
      name
      home_port
      image
    }
  }
}

{
    "limit": 10
}

GraphQL fragments are also supported and are included in the body by name.

fragment RocketParts on LaunchRocket {
  rocket_name
  first_stage {
    cores {
      flight
      core {
        reuse_count
        status
      }
    }
  }
}

POST https://api.spacex.land/graphql HTTP/1.1
Content-Type: application/json


query launchesQuery($limit: Int!){
  launchesPast(limit: $limit) {
    mission_name
    launch_date_local
    launch_site {
      site_name_long
    }
    rocket {
      ...RocketParts
    }
  }
}

{
    "limit": 10
}
 
























 







To import GraphQL File you need to use special GraphQL Import Directive.

POST https://api.spacex.land/graphql HTTP/1.1
Content-Type: application/json


gql launchesQuery < ./graphql.gql

{
    "limit": 10
}




 




TIP

You can use Variable Substitution in file import.

@assetsDir=./
POST https://api.spacex.land/graphql HTTP/1.1
Content-Type: application/json


gql launchesQuery < {{assetsDir}}graphql.gql

{
    "limit": 10
}





 




Request Separators

Multiple requests defined in a single file must be separated from each other with a request separator symbol. A separator may contain comments.

https://httpbin.org/post
### separator
https://httpbin.org/post

Alternatively, the request can also be specified in RFC 7230open in new window Request line format, which also triggers a separation.

GET https://httpbin.org/post HTTP/1.1

GET https://httpbin.org/post HTTP/1.1

Using ### Regions without a request can be defined. These global regions are executed and interpreted for all requests within the file. This way meta data, variables and scripts can be set for each request.

@host=https://httpbin.org
###
GET /post HTTP/1.1

GET /post HTTP/1.1

gRPC

It is also possible to send gRPC requests. The same request line format is used as for Http requests, but GRPC must be specified as the request method.

proto < ./hello.proto

GRPC grpcb.in:9000/hello.HelloService/sayHello
{
  "greeting": "world"
}

TIP

Own ChannelCredentials can be set simply using header channelCredentials.

proto < ./hello.proto

{{@request
const grpc = require('@grpc/grpc-js');
request.headers.channelcredentials = grpc.ChannelCredentials.createSsl();
}}
GRPC grpcb.in:9001/hello.HelloService/sayHello
{
  "greeting": "world"
}

Protobuf Loader

To use the gRPC call, the proto file associated with the call must first be loaded. This is loaded using @grpc/proto-loaderopen in new window. This can be configured using options in the header format

proto < ./hello.proto
keepCase: true
longs: String
enums: String
defaults: true
oneofs: true
includeDirs: [`${__dirname}/request`]

GRPC grpcb.in:9000/hello.HelloService/sayHello
{
  "greeting": "world"
}

The import of the proto file can also be done globally

proto < ./hello.proto

###
GRPC grpcb.in:9000/hello.HelloService/sayHello
{
  "greeting": "world"
}


GRPC grpcb.in:9000/hello.HelloService/sayHello
{
  "greeting": "john"
}

TIP

You can use Variable Substitution in file import and in proto-loader options.

@assetsDir=./

proto < {{assetsDir}}hello.proto
keepCase: true
longs: String
enums: String
defaults: true
oneofs: true
includeDirs: [`${assetsDir}/request`]

GRPC grpcb.in:9000/hello.HelloService/sayHello
{
  "greeting": "world"
}


 











::: warn IncludeDirs of @grpc/proto-loader currently supports only absolute paths. :::

Unary RPC

Unary RPCopen in new window behaves identically to Http requests. The url need to be in the following format

GRPC {{server}}/{{service}}/{{method}}
proto < ./hello.proto

GRPC grpcb.in:9000/hello.HelloService/sayHello
{
  "greeting": "world"
}

Using header notation it is also possible to send meta data.

Header ChannelCredentials or Authorizationare special and defines the authenticationopen in new window used by gRPC. If no such header is specified, grpc.credentials.createInsecure() is used automatically

Server Streaming RPC

Server Streaming RPCopen in new window is similar to a unary RPC, except that the server returns a stream of messages in response to a client’s request.

proto < ./hello.proto

GRPC grpcb.in:9000/hello.HelloService/LotsOfReplies
{
  "greeting": "world"
}

All responses are output as an intermediate result and summarized at the end as one overall response. If the intermediate results are not needed, they can be deactivated using # @noStreamingLog.

proto < ./hello.proto

# @noStreamingLog

GRPC grpcb.in:9000/hello.HelloService/LotsOfReplies
{
  "greeting": "world"
}

Client Streaming RPC

Client Streaming RPCopen in new window is similar to a unary RPC, except that the client sends a stream of messages to the server instead of a single message. To enable this, a custom script can be used that registers for the @streaming hook. This script must export a Promise at the end of which the client stream is terminated.

proto < ./hello.proto
GRPC grpcb.in:9000/hello.HelloService/lotsOfGreetings
{
  "greeting": "world."
}

{{@streaming

  async function writeStream(){
    await sleep(1000);
    grpcStream.write({
      greeting: 'How are you?',
    });
    await sleep(1000);
    grpcStream.write({
      greeting: 'I can stream.',
    });
  }
  exports.waitPromise = writeStream();
}}

TIP

To control the wait time more easily, a method sleep is provided that waits the number of milliseconds.

Bidirectional Streaming RPC

Bidirectional Streaming RPCopen in new window is a combination of client streaming and server streaming.

proto < ./hello.proto
GRPC grpcb.in:9000/hello.HelloService/BidiHello
{
  "greeting": "world"
}

{{@streaming

  async function writeStream(){
    await sleep(1000);
    grpcStream.write({
      greeting: ', how are you?',
    });
    await sleep(1000);
    grpcStream.write({
      greeting: ', I can stream.',
    });
  }
  exports.waitPromise = writeStream();
}}

Server-Sent Events / EventSource

By using method SSE an EventSourceopen in new window instance can be created. This opens a persistent connection to an HTTP server, which sends events in text/event-stream format. Adding the header event the list of events to be output is specified

SSE https://express-eventsource.herokuapp.com/events
Event: data

{{@streaming
  async function writeStream(){
    await sleep(10000);
  }
  exports.waitPromise = writeStream();
}}

 







The events of the server can be waited for by using streaming event. As soon as this hook has been successfully processed, the connection is terminated.

SSE https://express-eventsource.herokuapp.com/events
Event: data

{{@streaming
  async function writeStream(){
    await sleep(10000);
  }
  exports.waitPromise = writeStream();
}}



 
 
 
 
 
 

TIP

Meta Data keepStreaming can be used to respond to events until manually aborted.

# @keepStreaming
SSE https://express-eventsource.herokuapp.com/events
Event: data
 


WebSocket

By using method WS a WebSocket connectionopen in new window to a server can be opened. If a body is included in the request, it is sent immediately after the connection is established.

WS wss://demo.piesocket.com/v3/channel_1?api_key=oCdCMcMPQpbvNjUIzqtvF1d2X2okWpDQj4AwARJuAgtjhzKxVEjQU6IdCjwm&notify_self
{"foo": "bar"}

{{@streaming
  async function writeStream(){
    await sleep(10000);
    websocketClient.send('Hello World');
    await sleep(1000);
  }
  exports.waitPromise = writeStream();
}}
 










The events of the server can be waited for by using streaming event. As soon as this hook has been successfully processed, the connection is terminated. Within the streaming block it is possible to send further message using websocketClientopen in new window.

WS wss://demo.piesocket.com/v3/channel_1?api_key=oCdCMcMPQpbvNjUIzqtvF1d2X2okWpDQj4AwARJuAgtjhzKxVEjQU6IdCjwm&notify_self
{"foo": "bar"}

{{@streaming
  async function writeStream(){
    await sleep(10000);
    websocketClient.send('Hello World');
    await sleep(1000);
  }
  exports.waitPromise = writeStream();
}}






 




TIP

Meta Data keepStreaming can be used to respond to events until manually aborted.

# @keepStreaming
WS wss://demo.piesocket.com/v3/channel_1?api_key=oCdCMcMPQpbvNjUIzqtvF1d2X2okWpDQj4AwARJuAgtjhzKxVEjQU6IdCjwm&notify_self
 

TIP

All received messages are output as an intermediate result and summarized at the end as one overall response. If the intermediate results are not needed, they can be deactivated using # @noStreamingLog.

TIP

If special options are needed for initialization, they can be configured in a NodeJS script using request.optionsopen in new window.

MQTT

By using method MQTT a MQTT Client can be created. MQTT.jsopen in new window opens a TCP or WebSocket Connection to a MQTT Broker. The header Topic specifies the topic to be registered (multiple specification allowed)

# @keepStreaming
MQTT tcp://broker.hivemq.com
Topic: testtopic/1
Topic: testtopic/2

 


If a body is specified, it will be published immediately after connecting.

MQTT tcp://broker.hivemq.com
Topic: testtopic/1

Hello, World




 

TIP

If the topic used for publishing is different from the topic used for replying, the headers subscribe and publish can be used instead.

The messages of the server can be waited for using streaming event. As soon as this hook has been successfully processed, the connection is terminated. Within the streaming block it is possible to publish further message using mqttClientopen in new window.

MQTT tcp://broker.hivemq.com
Topic: testtopic/1

{{@streaming
  async function writeStream(){
    await sleep(1000);
    mqttClient.publish('testtopic/1', 'Hello World');
    await sleep(1000);
  }
  exports.waitPromise = writeStream();
}}






 




TIP

Meta Data keepStreaming can be used to respond to events until manually aborted.

# @keepStreaming
MQTT tcp://broker.hivemq.com
Topic: testtopic/1
Topic: testtopic/2
 



TIP

All received messages are output as an intermediate result and summarized at the end as one overall response. If the intermediate results are not needed, they can be deactivated using # @noStreamingLog.

QoSopen in new window, retain, username, password, keepAlive (10seconds default) and cleanopen in new window can be configured using header notation.

# @keepStreaming
MQTT tcp://broker.hivemq.com
Topic: testtopic/1
Qos: 1
username: foo
password: bar



 
 
 

TIP

If more options are needed for the initialization, they could be configured in a NodeJS script using request.optionsopen in new window.

As long as the connection of the MQTT instance to the MessageQueue exists, messages can also be published from other NodeJS blocks.

# @keepStreaming
MQTT tcp://broker.hivemq.com
Topic: testtopic/1

###
# @name test
{{
  mqttClient.publish('testtopic/1', 'hello johnny')
}}







 

AMQP/ RabbitMQ

By using method AMQP a AMQP Client can be created. @cloudamqp/amqp-clientopen in new window opens a AMQP Connection to RabbitMQ Server. Following Methods can be used

Publish

Publish a new message to an exchange. Header amqp_exchange defines the used exchange. amqp_routing_key is optional and sets the used routing key

AMQP amqp://guest:guest@localhost
amqp_method: publish
amqp_exchange: httpyac_exchange
amqp_routing_key: command.send

{
  "test": "{{$uuid}}"
}

 
 





A direct publish to a queue is available using amqp_queue.

AMQP amqp://guest:guest@localhost
amqp_queue: httpyac_queue

{
  "test": "test"
}

 




TIP

If no amqp_method header is present and a body is provided. publish is used as default

The following headers can also be defined

HeaderDescription
amqp_contentTypecontent type of body, eg. application/json
amqp_contentEncodingcontent encoding of body, eg. gzip
amqp_delivery_mode1 for transient messages, 2 for persistent messages
amqp_prioritybetween 0 and 255
amqp_correlation_idfor RPC requests
amqp_replyTofor RPC requests
amqp_expirationMessage TTL, in milliseconds, as string
amqp_message_idmessageId
amqp_user_iduserId
amqp_typetype

TIP

All other headers that do not start with amqp_ are appended to the message as headers

Consume/ Subscribe

Consume messages from a queue. Messages will be delivered asynchronously. The messages of the server can be waited for by using streaming event. As soon as this hook has been successfully processed, the connection is terminated. Within the streaming block it is possible to access additional methods of a AMQPChannel using amqpChannelopen in new window.

# @keepStreaming
AMQP amqp://guest:guest@localhost
amqp_method: consume
amqp_queue: httpyac_queue


 
 

TIP

Meta Data keepStreaming can be used to consume message until manually aborted.

TIP

If no amqp_method header is present and no body is provided. consume is used as default

AMQP amqp://guest:guest@localhost
amqp_queue: httpyac_queue

{{@streaming
  async function writeStream(){
    await sleep(10000);
  }
  exports.waitPromise = writeStream();
}}

 







TIP

All received messages are output as an intermediate result and summarized at the end as one overall response. If the intermediate results are not needed, they can be deactivated using # @noStreamingLog.

The following headers can also be defined

HeaderDescription
amqp_tagtag of the consumer, will be server generated if left empty
amqp_no_ackf messages are removed from the server upon delivery, or have to be acknowledged
amqp_exclusiveif this can be the only consumer of the queue, will return an Error if there are other consumers to the queue already

Ack/ Nack/ Cancel

Consumed messages are not acked/ nacked automatically. If a message needs to get acked/ nacked automatically a manual ack/ nack needs to be called. You need to declare the same channelId (amqp_channel_id) and deliveryTag (amqp_tag) as the consumer.

AMQP amqp://guest:guest@localhost
amqp_method: ack
amqp_channel_id: 1
amqp_tag: 2

 


AMQP amqp://guest:guest@localhost
amqp_method: nack
amqp_channel_id: 1
amqp_tag: 2

 


AMQP amqp://guest:guest@localhost
amqp_method: cancel
amqp_channel_id: 1
amqp_tag: 2

 


The following headers can also be defined

HeaderDescription
amqp_requeueif the message should be requeued or removed
amqp_multiplebatch confirm all messages up to this delivery tag

Purge

Purge all messages of a queue

AMQP amqp://guest:guest@localhost
amqp_method: purge
amqp_queue: httpyac_queue

 

Declare exchange

Declare a queue or exchange

AMQP amqp://guest:guest@localhost
amqp_method: declare
amqp_exchange: httpyac_exchange

 

AMQP amqp://guest:guest@localhost
amqp_method: declare
amqp_queue: httpyac_queue

 

HeaderDescription
amqp_passiveif the exchange name doesn't exists the channel will be closed with an error, fulfilled if the exchange name does exists
amqp_durableif the exchange should survive server restarts
amqp_auto_deleteif the exchange should be deleted when the last binding from it is deleted
amqp_exclusiveif the queue should be deleted when the channel is closed

Bind/ Unbind queue to exchange

Bind and unbind queue of a exchange

AMQP amqp://guest:guest@localhost
amqp_method: bind
amqp_exchange: httpyac_exchange
amqp_queue: httpyac_queue
amqp_routing_key: command.send

 



AMQP amqp://guest:guest@localhost
amqp_method: unbind
amqp_exchange: httpyac_exchange
amqp_queue: httpyac_queue
amqp_routing_key: command.send

 



Bind/ Unbind exchange to exchange

Create or delete an Exchange to exchange binding

AMQP amqp://guest:guest@localhost
amqp_method: bind
amqp_exchange: httpyac_exchange
amqp_exchange_destination: httpyac_exchange2
amqp_routing_key: command.send

 



AMQP amqp://guest:guest@localhost
amqp_method: unbind
amqp_exchange: httpyac_exchange
amqp_queue: httpyac_queue
amqp_routing_key: command.send

 



Delete

Delete an exchange or queue

AMQP amqp://guest:guest@localhost
amqp_method: delete
amqp_exchange: httpyac_exchange

 

AMQP amqp://guest:guest@localhost
amqp_method: delete
amqp_queue: httpyac_queue

 

HeaderDescription
amqp_if_unusedonly delete if the exchange doesn't have any bindings
amqp_if_emptyonly delete if the queue is empty
Last Updated: