HTTP client for Sublime Text
RESTer allows you to build an HTTP request in Sublime Text and view the response in a new tab.
A request can be as simple as a URI:
http://api.my-example-site.com
Or, you can send headers and a body:
PUT /my-endpoint HTTP/1.1
Host: api.my-example-site.com
Accept: text/plain
Accept-Charset: utf-8
X-custom-header: whatever you want
Here is the payload for the PUT request. Just add an empty line after the headers.
Once you have a request ready, use shortcut Ctrl + Alt + r or open the Command Palette (Shift + Command + P) and enter RESTer HTTP Request.
You can install RESTer using the excellent Package Control package manager for Sublime Text:
- Open "Package Control: Install Package" from the Command Palette (
Shift + Command + P). - Select the "RESTer" option to install RESTer.
To install, clone to your "Packages" directory.
git clone https://github.com/pjdietz/rester-sublime-http-client.git "RESTer HTTP Client"
Note RESTer expects to be installed to a directory called "RESTer HTTP Client". Some features like the meny command to open settings will not work if installed somewhere else.
The first non-empty line of the selection (or document if nothing is selected) is the "request line". RESTer parses this to determine the method, URI, and protocol.
You may include the hostname in the request line, but RESTer does not require it. If omitted, be sure to include a Host header indicating the hostname.
Here are some example request lines:
GET /my-endpoint HTTP/1.1
Host: api.my-example-site.com
GET http://api.my-example-site.com/my-endpoint
http://api.my-example-site.com/my-endpoint
api.my-example-site.com/my-endpoint
Because GET is the default method, each of these will have the same effect.
RESTer parses the lines immediately following the first non-empty line up to the first empty line as headers. Use the standard field-name: field-value format.
For requests with many query parameters, you may want to spread your request across a number of lines. RESTer will parse any lines in the headers section that begin with ? or & as query parameters. You may use = or : to separate the key from the value.
The following example requests are equivalent:
All in the URI
http://api.my-example-site.com/?cat=molly&dog=bear
With new lines
http://api.my-example-site.com/
?cat=molly
&dog=bear
Indented, using colons, and only using ?
http://api.my-example-site.com/
? cat: molly
? dog: bear
One thing to note is that RESTer assumes that anything you place directly in the request line is the way you want it, but query parameters added on individual lines are assumed to be in plain text. So, values of query parameters added on individual lines are percent encoded.
These requests are equivalent:
http://api.my-example-site.com/?item=I%20like%20spaces
http://api.my-example-site.com/
? item: I like spaces
To supply a message body for POST and PUT requests, add an empty line after the last header. RESTer will treat all content that follows the blank line as the request body.
Here's an example of adding a new cat representation by supplying JSON:
POST http://api.my-example-site.com/cats/
{
"name": "Molly",
"color": "Calico",
"nickname": "Mrs. Puff"
}
For application/x-www-form-urlencoded requests, you can use the auto_form_encode command (part of RESTer) to automatically encode a body of key-value pairs. To use this functionality, make sure that auto_form_encode is enabled as a request_command and include a Content-type: application/x-www-form-urlencoded header.
The key-value pairs must be on separate lines. You may use = or : to separate the key from the value. As with query parameters, whitespace around the key and value is ignored.
Example:
POST http://api.my-example-site.com/cats/
Content-type: application/x-www-form-urlencoded
name=Molly
color=Calico
nickname=Mrs. Puff
Colons and whitespace
POST http://api.my-example-site.com/cats/
Content-type: application/x-www-form-urlencoded
name: Molly
color: Calico
nickname: Mrs. Puff
Use delimiters to mark the boundaries of multiline field values. By default, the delimiters are """ to mimic a triple-quoted Python string. You may customize this by providing values for the form_field_start and form_field_end settings.
Here's an example of a request using mixed single- and multiline fields.
POST http://api.my-example-site.com/cats/
Content-type: application/x-www-form-urlencoded
name: Molly
color: Calico
nickname: Mrs. Puff
extra: """{
"id": 2,
"description": "This JSON snippet is wrapped in delimiters because it has multiple lines."
}"""
You may include comments in your request by adding lines in the headers section that begin with #. RESTer will ignore these lines.
GET /my-endpoint HTTP/1.1
Host: /api.my-example-site.com
# This is a comment.
Cache-control: no-cache
RESTer has some other features that you can customize through settings. To customize, add the desired key to the user settings file.
You may also provide configuration settings for the current request by adding lines to the headers section that begin with @.
The format of the line is @{name}: {value} where {name} is the key for a setting and {value} is the value. The value is parsed as a chunk of JSON.
GET /my-endpoint HTTP/1.1
Host: /api.my-example-site.com
@timeout: 2
@default_response_encodings: ["utf-8", "ISO-8859-1", "ascii"]
By default, RESTer outputs the request and response to the console and opens a new buffer where it writes the full contents of the response. This view is created in the same group as the request view. You can change this behavior by tweaking several settings.
| Setting | Default | Description |
|---|---|---|
| output_request | true |
Write the request to the console. |
| output_response_headers | true |
Write the status line and headers to the console. |
| output_response_body | true |
Write the body of response to the console. Note: because response commands must by run in a buffer, the body is not processed. |
| response_buffer | true |
Open a new buffer, write the response, and run any number of response commands on the response body. |
| response_group | null |
Set to the integer index of the group the response should appear in. 1 is the typical choice for a two-column presentation. |
| response_group_clean | false |
If indicating a specific response_group, close all other views in that group on each response. |
| request_focus | false |
Return focus to the request view after displaying the response. |
| body_only | false |
When writing the response to the buffer, do not include headers. |
If you'd like to author your request in one panel and view your response in a second, use this configuration:
{
"response_group": 1,
"response_group_clean": true,
"request_focus": true
}As of version 1.3.0, RESTer supports making HTTP and HTTPS requests. To use HTTPS, you can include the protocol in the request line. You can also set a default protocol in the settings.
{
"protocol": "https"
}You may also set the protocol using an override. These requests are equivalent:
GET https://api.my-secure-example-site.com/my-endpoint
GET /my-endpoint
Host: api.my-secure-example-site.com
@protocol:https
Note for Linux Users: The Python interpreter in Sublime Text on Linux does not have SSL support. To make HTTPS requests, you will need to change the RESTer settings to use cURL.
RESTer will open the connection to the host it finds in the Host header or in the request line. Hoever, you may want to communicate with a server at a specfic IP address. Do do this, use the @host setting.
GET /my-endpoint
Host: api.my-example-site.com
@host: 127.0.0.1
RESTer will assume ports 80 and 443 for HTTP and HTTPS respectively. If you ofter require a specific custom port, you can set it with the @port setting.
GET /my-endpoint
Host: api.my-example-site.com
@host: 127.0.0.1
@port: 8888
To include a set of headers with each request, add them to the "default_headers" setting. This is a dictionary with the header names as the keys.
{
"default_headers": {
"Accept-Encoding": "gzip, deflate",
"Cache-control": "no-cache"
}
}RESTer can try to discern the encoding for a response. This doesn't always work, so it's a good idea to give it some encodings to try. Do this by supplying a list for the "default_response_encodings" setting.
{
"default_response_encodings": ["utf-8", "ISO-8859-1", "ascii"]
}After RESTer writes the response into a new tab, it selects the response body. With the body selected, it can perform a series of operations on the text. For example, you could instruct RESTer to pretty-print JSON responses.
To specify commands for RESTer to run on the response, add entries to the response_commands member of the settings. The value for response_commands must be a list of string names of commands.
{
"response_commands": ["pretty_json"]
}If you don't have the PrettyJson package installed, nothing bad will happen. You won't get any errors, but you won't get any pretty printed JSON either.
If you're not sure what the command is for a given feature, you may be able to read its name from the command history. Run the command as you normally would, then open the Python console (Ctrl + `), and enter view.command_history(0). You should see the last command that was run on the current view.
>>> view.command_history(0)
('insert', {'characters': '\n\n'}, 1)Start by finding the name of the syntax file. To view the current syntax, use the Python console:
>>> view.settings().get("syntax")
'Packages/HTTP Spec Syntax/httpspec.tmLanguage'Use the bundled set_syntax command to set the syntax of any new resposes to the syntax file you chose. Here we are using "Packages/HTTP Spec Syntax/httpspec.tmLanguage", a syntax for HTTP messages that is part of the httpspec/sublime-highlighting package.
{
"response_commands": [
{
"name": "set_syntax",
"args": {
"syntax_file": "Packages/HTTP Spec Syntax/httpspec.tmLanguage"
}
}
]
}Notice that this command requires a syntax_file parameter. See Request and Response Commands with Parameters below to learn more about running commands with parameters.
RESTer can perform operations on the text of your request before it parses it. These commands are undone after the request is made, so your file is never modified. As with response commands, you'll specify these by adding a list entry to the settings file. This time, the setting name is request_commands.
{
"request_commands": ["merge_variables"]
}A useful command to use as a request command is merge_variables from my Merge Variables package. Using Merge Variables, you can write your requests using placeholder variables that are not expanded until the moment you make the request. Merge Variables allows you to specify multiple configurations as well, so you can build a request once, and have it merge in various configurations. For example, you could start with this request:
GET http://{{API}}/my-endpoint
For a development configuration, this could expand to:
GET http://dev.my-example-site.com/my-endpoint
And for a production configuration:
GET http://api.my-example-site.com/my-endpoint
See Merge Variables for more information.
Most of the time, you'll only need to supply the name for a command. Some commands can take parameters, and you can pass these in by supplying an object instead of a string for your command. To use the object format, be sure to include the name of the command as the name member, and any parameters as the args member.
{
"name": "merge_variables",
"args": {
"active_sets": ["mysite", "mysite-dev"]
}
}RESTer will follow redirects automatically. To disable this or limit the response codes which will trigger an automatic redirect, modify these settings (defaults shown):
{
"follow_redirects": true,
"follow_redirect_status_codes": [300, 301, 302, 303, 307]
}If you have cURL installed, you can set RESTer to use cURL instead of the Python http.client library. Most users will not need to do this, but this may be helpful for Linux users that are unable to make HTTPS requests because Python was not compiled with SSL support. Or, if you're familiar with using cURL on the command line, you may find it useful to add custom arguments to the cURL command.
There are three settings related to cURL. The first is http_client which tells RESTer which client to use (allowed values are python for the native Python connector or curl for cURL.).
Next is curl_command which is the path to the cURL executable. On OSX and Linux, if curl is on your path, you will not need to change this. Windows users providing a full path to curl.exe will need to use forward slashes in the path (e.g., C:/curl/curl.exe).
The last setting is curl_options, an optional list of arguments to pass to the curl executable. Each option must be a separate string, so to send a custom header, use ["--header", "X-custom-header: header-value"], not "--header X-custom-header: header-value". Here's an example showing these three settings:
{
"http_client": "curl",
"curl_command": "C:/curl/curl.exe",
"curl_options": ["--header", "X-custom-header: header-value"]
}For more information on cURL, see the cURL man page
PJ Dietz
Copyright 2013 PJ Dietz