chainable-fetch
The JSON friendly, string free HTTP request client.
chainable-fetch
is a HTTP request client tailored for JSON and ease of use.
Most request libraries focus on single requests, chainable-fetch
focuses on api reuse.
It uses the chainable library and fetch
under the hood (node-fetch in node)
to provide a clean, hassle free experience.
No more messy strings—just code.
chainable-fetch
uses Proxy
objects to build a request, rather than having to specify a string url.
; const api = ;const response = await apiv1users;
The default mode for chainable-fetch
is JSON!
JSON is the standard, not the exception.
All request bodies and responses are automatically JSON stringified/parsed for you. chainable-fetch
assumes you're interacting with a JSON API. However, non-JSON requests are definately supported,
just set the request type to text
, buffer
or any other supported type.
Configure request options once:
You setup the headers, request type (text, json, etc.) when you create your API reference once.
All requests will use these options and you can override them at the individual request level
for edge cases.
This reduces code quantity and allows defaults to be set in a single place.
Other Features
- Request/Response Interceptors
- Custom Fetch Implementations
- Create Custom Request Types (XML, etc.)
- Piping Responses
- Buffer Responses
- Support for Node 6+ and browsers with
fetch
andProxy
available.
See the caveat about browser support!
Install
$ npm install chainable-fetch --save
Usage
; const swapi = ; // Make a couple of HTTP requests to the Star Wars API...// GET https://swapi.co/api/starships// GET https://swapi.co/api/planetsconst starships planets = await Promiseall swapistarships swapiplanets; // You can even reference endpoints.const people = swapipeople;const person = await people1; // You can chain together any endpoint!const exampleApi = ; await exampleApifoobarbaxquxx;await exampleApifoobarbaxquxx; // Dynamic endpoints? Lodash's `get` method comes in handy...await _;
The following methods are supported:
- get
- put
- post
- patch
- head
- delete
Examples
// This is useful if you version up your api!// Now, when the next version comes out, you can simply change `v1` to `v2`.const services = v1; const user = await servicesuser; const result = await servicesuser; // Oops... my api has the keywords "get", "post", "put" in them...// Seems silly, but you can use the `path` method.// this will GET from https://my-api.com/user/getawait servicesuser;
Setting Up Your API
When you create your chainable api, the following options are supported:
; // You can specify only a string to use the default options (JSON).const api = ; // Or, you can provide options.// The `host` property is required, defaults shows.const api =
Making Requests
When you make a request, the following options are supported by every request method:
; const services = ; const response = await servicessomeendpointget|post|put|delete|patch|head // The query to append to the url. // This will be converted from an object to a querystring. // Note, this is slightly different than node's querystring.stringify, // since object values are automatically JSON.stringified. query: ... // The POST/PUT body // Can be a string, object, FormData, etc. body: ... // Key/value header pairs. // These will override any headers provided during api creation. headers: ... // The request type. // Can be one of: 'json', 'text', 'buffer', 'blob'. // Overrides the api's request `type` option above. type: 'json' // If true the actual "raw" fetch response will be returned. // Overrides the api's `raw` option above. raw: false // Any other node fetch option... // See https://github.com/bitinn/node-fetch#options for more info. follow timeout compress size agent
Request Types
"Request Types" are a interface that defines how a request body is serialized and the response
is deserialized. For example, the json
request type stringifies the body and parses the response.
The following are available by default:
- json
- text
- buffer
- blob
Custom Request Types
You can create custom request types (or override default ones) using the setRequestType
export.
; // An example of the `json` request type.
Here's an example of implementing a custom XML request type.
;; ; const services = ; // POSTs '<user id="5">Chunk Norris</user>' to https://my-xml-api.com/user// The response, per our request type, would be XML converted to a js object.const response = await servicesuser;
Webpack Usage
You'll need to ignore node-fetch
in your webpack config to prevent it from being included in your
bundle and blowing up.
/^node-fetch$/