-
Notifications
You must be signed in to change notification settings - Fork 8
/
roast.txt
277 lines (217 loc) · 9.12 KB
/
roast.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
*roast.txt* An HTTP client for ViM
Author: Shrikant Kandula <https://sharats.me>
Repo: https://github.com/sharat87/roast.vim
License: See LICENSE file.
USAGE *roast*
Open (or create) a file with the extension of `.http` or `.roast` and the roast
plugin will be active in that buffer. Now put the following text in that file
and hit the <Enter> key while the cursor is on that line:
>
GET http://httpbin.org/get answer=42
<
The output of this `GET` request should show up in a new vertically split
window. The line itself should highlight in a shade of green. If the request
was a failure, you'd see that the line would highlight in a shade red.
FEATURES OVERVIEW *roast-features*
- Syntax roughly similar to HTTP protocol requests.
- Headers apply to all requests below that header definition line.
- A single session is used for all requests from a buffer. That is, cookies are
preserved across requests from a single buffer.
- Simple string variables support that can be used for interpolation.
- Variable interpolation is implemented with Python's `.format` syntax.
- Variable interpolation works in request paths, query params, header values,
request bodies, other variable definitions.
- Each line is parsed with Python's `shlex` module. That is, comments start with
`#`, quotes should be used to specify strings with special characters such as
spaces.
A good place to find working examples would be the `python3/test_roast.py`
module where several of the above features are tested.
HEADERS *roast-headers*
The syntax for setting headers is similar to how they appear in an actual HTTP
request.
>
Accept: application/json
<
This line will ensure that this header is set to all requests that are below
this line. For example, consider the following file:
>
GET /url/path/1
Accept: application/json
GET /url/path/2
<
If you place the cursor on the request for `/url/path/1` and hit <Enter>, the
`Accept` header is not sent. If, however, you place the cursor on the request
for `/url/path/2` and hit <Enter>, the header is sent. The header is sent for
any and all requests below `/url/path/2` as well.
The header can be given a different value somewhere down and that will be
effective from that point on in the file.
To remove the header, set the header with no value. Like:
>
Accept:
<
No `Accept` header will be sent on the following requests.
DIRECTIVES *roast-directives* *roast-use*
Roast has `use` directives that configure the behaviour of Roast. Currently,
there only one directive that can be used with `use`:
URL Prefix: *roast-url_prefix*
>
use url_prefix https://httpbin.org
<
After this line, a request like `GET /url` would actually run a GET request to
`https://httpbin.org/url`. The value given to `url_prefix` can contain path
elements as well.
To unset the `url_prefix`, don't provide a value, just like for headers. Like
this:
>
use url_prefix
<
REQUEST QUERY PARAMS
Query parameters can be given as part of the URL in the usual fashion,
>
GET http://httpbin.org/get?key1=value1&key2=value2
<
Note that the URL is processed with python's `.format` with |roast-variables|
so variable interpolation can be used here.
But it is usually more convenient to use spaces that roast.vim allows instead
of the `&` and `?` marks. The above can be written as:
>
GET http://httpbin.org/get key1=value1 key2=value2
<
In this form, only the values support interpolation. For example,
>
set answer 42
GET http://httpbin.org/get text=number_{answer}
<
This sends a request to the following URL:
>
http://httpbin.org/get?text=number_42
<
There's also a shortcut for the following common use case:
>
set answer 42
GET http://httpbin.org/get answer={answer}
<
This can be written as:
>
set answer 42
GET http://httpbin.org/get answer
<
Both send request to the following URL:
>
http://httpbin.org/get?answer=42
<
REQUEST BODY *roast-post-body*
The body for POST or other requests can be specified using heredoc-like syntax.
This is best illustrated with an example:
>
POST http://httpbin.org/post << body
here goes the post body
this content is passed to the POST request as-is.
body
<
The heredoc marker is `body` here. It can be any alphanumeric string.
Mark the heredoc as `RAW` to avoid any variable interpolation:
>
POST http://httpbin.org/post << RAW
{
"username": "Sherlock",
"password": "Moriarty"
}
RAW
<
The verbatim JSON string will be sent as body.
Mark the heredoc as `JINJA2` to render the body with the jinja2 template:
>
set name Sherlock
set password Moriarty
POST http://httpbin.org/post << JINJA2
{
"username": "{{name}}",
"password": "{{password}}"
}
JINJA2
<
Note that the `jinja2` package needs to be installed to use this feature.
The variables will be used to render the body and the final body would be
like:
>
{
"username": "Sherlock",
"password": "Moriarty"
}
<
USING VARIABLES *roast-variables*
Variables allow for interpolation within braces and this lets us create nice
little DSL's made up of HTTP APIs.
The syntax to set a variable is as following:
>
set name value
<
If the value contains spaces or special characters, it can be surrounded by
quotes, similar to escaping semantics of a shell. Note the variable
interpolations are allowed in the value part of this syntax.
Variable interpolations are powered by Python's `str.format` method. If you're
not familiar with that method, don't worry, here's what it looks like:
>
set first_name Elijah
set last_name Baley
set full_name {first_name}_{last_name}
<
The variable `full_name` will be set to `Elijah_Baley`.
Variable interpolations work in header values, URL's, query parameter values and
other variable declarations. A variable can be set to a different value with the
same file. Only the closest `set` above the current line will be taken into
consideration.
A neat shortcut regarding interpolation in query params is that it is possible
to use params already set for interpolation in later params, with the name
prefixed with the `@` symbol. That doesn't make sense, I know, but an example
will click right away. Here it is:
>
GET https://httpbin.org/get first=Jon last=Snow full={@first}_{@last}
<
Get it now? :)
A note about escaping braces in the context of interpolation. Braced should be
doubled to escape. So, if we are defining a variable with a JSON value, the
braces should be doubled so they won't be interpreted as interpolation targets.
<
set payload '{{"username": "Sherlock", "password": "Moriarty"}}'
>
Here, the variable `payload` would be set to the following text:
<
{"username": "Sherlock", "password": "Moriarty"}
>
This is covered in the test `test_variable_with_json_value`.
VIEWING RESPONSE *roast-viewing-response*
When a request is run (by hitting the <Enter> key, by default), a new window is
opened by splitting vertically, unless a window is already displaying a roast
result.
This window will show the response of the query with json syntax highlighting if
the appropriate response header is present.
To view other details of the request/response, go to the window displaying a the
result and hit <C-j> or <C-k> to cycle between several renderers of the response
data.
There is a provision for custom renderers, but it's not mature enough to be
documented and encouraged in the wild. Coming soon.
TIPS *roast-tips*
1. Switch the `url_prefix` between various staging servers of your app.
For example, if we have http://dev.staging.example.com/ as our dev server and
http://qa.staging.example.com/ as our QA server, we can set the `url_prefix` in
our roast file in the first line like:
>
use url_prefix http://dev.staging.example.com/
<
With this, we can have a hotkey to switch this host between dev and QA hosts.
This can be achieved with something like the following (to be put in
~/.vim/after/ftplugin/roast.vim):
>
py3 import vim
nnoremap <silent> <buffer> <LoacalLeader>d :py3 vim.current.buffer[0] = 'use url_prefix http://dev.staging.example.com/'
nnoremap <silent> <buffer> <LoacalLeader>q :py3 vim.current.buffer[0] = 'use url_prefix http://qa.staging.example.com/'
<
Of course, this is very basic, it assumes the `url_prefix` directive is on the
first line or overwrites that line when the hotkey is hit.
More tips coming soon!
ABOUT *roast-about*
Roast plugin is developed by sharat87. Contributions welcome. If you notice
a bug or have an idea for a feature request, please open an issue on GitHub.
vim:ft=help