solicit

a declarative http client for node and browser

npm install solicit
14 downloads in the last month

solicit

a declarative http client based of superagent. Versions available for both the browser and node with the same API and shared test suite. Usable now but still a WIP. A little bit experimental also so API is unstable.

Installation

With packin or component

$ packin add jkroso/solicit

then in your app:

var request = require('solicit')

Example

request.get('component.io/components/all').read(console.log) // => a whole lot of JSON

API

Solicit.verb(url:String|Object)

Each http verb has a corresponding helper function for making that type of request. Each function will return a Request. Requests are deferred results so you are free to configure them as much as you like with the methods mentioned below then call read() or then() to actually send the request and read the response. The main verbs you will be using are:

  • get
  • post
  • put
  • head
  • delete

Request.set(field:String|Object, val:String)

Set header field to val, or multiple fields with one object.

Examples:

request.get('/')
  .set('Accept', 'application/json')
  .set('X-API-Key', 'foobar')
  .read(callback)
request.get('/')
  .set({ Accept: 'application/json', 'X-API-Key': 'foobar' })
  .read(callback)

Request.get(field)

Get request header field.

Request.query(val:Object|String)

Add query-string val.

Examples:

request.get('/shoes')
  .query('size=10')
  .query({ color: 'blue' })

Request.type(type)

Set the "Content-Type" header. Common types can be set with a shorthand string:

request.post('/')
  .type('application/json')
  .send(jsonstring)
  .read(callback)
request.post('/')
  .type('json')
  .send(jsonstring)
  .read(callback)

Request.accept(type)

Set the "Accept" header. As with Request.type() shorthand strings are allowed

Request.timeout(ms)

Set timeout to ms.

Request.clearTimeout()

Clear previous timeout.

Request.abort()

Abort and clear timeout.

Request.agent(agent:http.Agent)

Gets/sets the Agent to use for this HTTP request. The default (if this function is not called) is to opt out of connection pooling (agent: false).

Request.send(data:String|Object)

Send data, defaulting the .type() to "json" when an object is given.

Examples:

// manual json
request.post('/user')
  .type('json')
  .send('{"name":"tj"}')
  .read(callback)
// auto json
request.post('/user')
  .send({ name: 'tj' })
  .read(callback)
// manual x-www-form-urlencoded
request.post('/user')
  .type('form')
  .send('name=tj')
  .read(callback)
// auto x-www-form-urlencoded
request.post('/user')
  .type('form')
  .send({ name: 'tj' })
  .read(callback)
// string defaults to x-www-form-urlencoded
request.post('/user')
  .send('name=tj')
  .send('foo=bar')
  .send('bar=baz')
  .read(callback)

Request.auth(user, pass)

Set Authorization field value with user and pass

Request.maxRedirects(n)

Set the max redirects to n.

Request.path(...)

Set the path. arguments is joined to form the path:

get('https://api.github.com')
  .path('repos', user, repo, 'tags')
  .read(callback)

Request.write(data:Buffer|String, [encoding='utf8'])

Write data to the socket.

Request.end([data]:Buffer|String, [encoding='utf8'])

send request

Request.pipe(stream, options)

Pipe the request body to stream

Running the tests

Just run make and navigate your browser to test/index.html.

npm loves you