rester-client v1.0.3
RESTer Client
RESTer Client is a library for making HTTP requests from strings. It's the core of the RESTer Atom package.
Overview
Using RESTer Client involves creating a Client
, and then using that Client
to generate Transactions
. Each Transaction
represents a single request-response cycle, including redirects.
// Import the Client constructor.
const Client = require('rester-client');
// Create a Client instance.
let client = new Client();
// Use the Client to create a Transaction for a specific request.
let transaction = client.request(`
POST /cats/ HTTP/1.1
Host: localhost:8080
Content-type: application/json
{
"name": "Molly",
"color": "calico"
}
`);
// Add event listeners for transaction events.
transaction.on('end', () => {
// Display the last response received.
console.log(transaction.getResponse());
// Clean up when done.
transaction.removeAllListeners();
transaction = null;
});
transaction.on('error', (err) => {
console.log('Oh noez! Something went wrong!');
// Clean up when done.
transaction.removeAllListeners();
transaction = null;
});
// Send the request.
transaction.send();
Client
The 'rester-client'
module provides the Client
constructor function. A Client
instance serves as a factory for creating Transactions
. To create a Transaction
, pass a string to the client's request()
method. See Parsing for information on how to write requests.
When you a create Client
instance, you can pass an optional configuration object to tailor the client's behavior to your needs.
To create a client that will follow redirects for status codes 301, 302, and 303:
let client = new Client({
followRedirects: true,
redirectStatusCodes: [301, 302, 303]
});
Options
Option | Type | Default | Description |
---|---|---|---|
followRedirects | boolean | false | When true , will automatically redirect responses with status codes listed in redirectStatusCodes . |
redirectStatusCodes | array | [] | When followRedirects is true , will automatically redirect responses with status codes listed in this array. |
multilineEnd | string | """ | Delimiter marking the end of a multiline form field |
multilineStart | string | """ | Delimiter marking the start of a multiline form field |
These and many other settings can be overridden when parsing the request. See the Parsing section for details.
Transactions
A Transaction
represents a single request-response cycle. To create a Transaction
, pass a string representing the request to a Client
's request()
method.
let transaction = client.request('GET http://localhost:8080/path');
Next, add event listeners. 'end'
and 'error'
are the most commonly used.
transaction.on('end', () => {
console.log('We received a response. Here it is:');
console.log(transaction.getResponse());
// Clean up when done.
transaction.removeAllListeners();
transaction = null;
});
transaction.on('error', (err) => {
console.log('Oh noez! Something went wrong!');
// Clean up when done.
transaction.removeAllListeners();
transaction = null;
});
Call send()
to send the request.
transaction.send();
Events
Event | Description |
---|---|
'request' | Send an outgoing request |
'response' | Received an incoming response |
'redirect' | Sent an additional request |
'end' | Received a final response |
'error' | Encountered an error. The error is passed as a parameter |
Methods
Method | Description |
---|---|
getRequest() | Returns the initial request as a string |
getResponse() | Returns the most recently received response as a string |
send() | Send the initial request to begin the transaction |
See EventEmitter documentation for information on adding and removing event listeners.
Properties
Property | Type | Description |
---|---|---|
configuration | object | Object of configuration options propagated from the Client or set in the request. |
requests | array | Array of string requests sent. |
responses | array | Array of string responses received. |
Parsing
The string you use to create a transaction can be as simple as a URI:
http://localhost:8080/path
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. The body is anything that follows the first empty line.
The Request Line
The first non-empty, non-comment (//
or #
) line 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.
Here are some example request lines (some with Host headers):
GET /my-endpoint HTTP/1.1
Host: api.my-example-site.com
GET /my-endpoint
Host: api.my-example-site.com
GET http://api.my-example-site.com/my-endpoint
http://api.my-example-site.com/my-endpoint
Headers
RESTer parses the lines immediately following the request line up to the first empty line as headers. Use the standard field-name: field-value format.
GET /path HTTP/1.1
Host: localhost:8080
Cache-control: no-cache
If-Modified-Since: Mon, 8 Sept 2014 13:0:0 GMT
Query Parameters
For requests with many query parameters, you may want to spread your query 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
Percent Encoding
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 will be 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
Comments
Include comments in your request by adding lines in the headers section that begin with #
or //
. RESTer will ignore these lines.
GET /my-endpoint HTTP/1.1
Host: /api.my-example-site.com
# This is a comment.
// This is also a comment.
Cache-control: no-cache
Body
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/
Content-type: application/json
{
"name": "Molly",
"color": "Calico",
"nickname": "Mrs. Puff"
}
Forms
To submit a form (i.e., application/x-www-form-urlencoded
), include the @form
option in the header section. This option instructs RESTer to add the appropriate Content-type
header and encode the body as a form.
Include the key-value pairs 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.
Examples:
POST http://api.my-example-site.com/cats/
@form
name=Molly
color=Calico
nickname=Mrs. Puff
POST http://api.my-example-site.com/cats/
@form
name: Molly
color: Calico
nickname: Mrs. Puff
Multiline Values
Use delimiters to mark the boundaries of multiline field values. By default, the delimiters are """
. You may customize these providing multilineStart
and multilineEnd
options when calling the Client
constructor.
Here's an example of a request using mixed single- and multiline fields.
POST http://api.my-example-site.com/cats/
@form
name: Molly
color: Calico
nickname: Mrs. Puff
extra: """{
"id": 2,
"description": "This JSON snippet is wrapped in delimiters because it has multiple lines."
}"""
Options
To customize RESTer's behavior for a single transaction, include options in the header section. An option begins with @
and may or may not include a value. For example, to instruct RESTer to follow redirects, include @followRedirects
like this:
GET http://localhost:8080/path-that-redirects
@followRedirects: true
Boolean true
options can also be expressed with a shorthand syntax by including the option key without the :
and value. This is equivalent:
GET http://localhost:8080/path-that-redirects
@followRedirects
Some options accept strings or arrays as values. For example:
GET http://localhost:8080/path-that-redirects
@followRedirects
@redirectStatusCodes: [301, 302]
The following is a list of options that RESTer expects:
Option | Type | Description |
---|---|---|
@auth | string | Auth segment for the request (e.g., "user", "user:password") |
@followRedirects | boolean | Allow RESTer to automatically follow redirects |
@form | boolean | Parse the body as a form and include the appropriate Content-type header |
@hostname | string | Hostname for the request (e.g., "localhost") |
@port | int | Port for the request (e.g., 8080) |
@protocol | string | Protocol for the request. Must be "http" or "https" |
@redirectStatusCodes | array | List of status codes to automatically follow redirects for |
All configuration options—including those provided by the Client and those parsed from the request string—are made available as the transaction's configuration
property. This even includes unexpected options with no inherent meaning to the core RESTer module. This feature allows you to create your own options when building software that uses RESTer Client.
For example, RESTer for Atom allows the user to customize whether or not to display redirect responses in the output by including @showRedirects
in the request.
Unit Tests
Run all tests:
npm test
Run a test or directory of tests:
npm test -- [path to file or directory relative to test/tests]
To run tests with code coverage, include the -c
or --coverage
option.
npm test -- -c [path]
npm test -- --coverage [path]
The code coverage report will be created at coverage/lcov-report/index.html
.
Author
PJ Dietz
Copyright and license
Copyright 2016 by PJ Dietz