browser-fetch-json
<img src=https://raw.githubusercontent.com/center-key/browser-fetch-json/master/logos.png
align=right width=200 alt=logos>
A thin wrapper around the browser's native Fetch API just for JSON
Why would you fetch anything but json? ;)
1) Setup
In a web page:
<script src=fetch-json.min.js></script>
From the jsdelivr.com CDN:
<script src=https://cdn.jsdelivr.net/npm/browser-fetch-json@0.2/fetch-json.min.js></script>
Or install as a module:
$ npm install browser-fetch-json
Then import with:
const fetchJson = require('browser-fetch-json');
2) Examples
HTTP GET
Fetch the NASA Astronomy Picture of the Day:
const url = 'https://api.nasa.gov/planetary/apod';
const params = { api_key: 'DEMO_KEY' };
function handleData(data) {
console.log('The NASA APOD for today is at: ' + data.url);
}
fetchJson.get(url, params).then(handleData);
HTTP POST
Create a resource for the planet Jupiter:
const resource = { name: 'Jupiter', position: 5 };
function handleData(data) {
console.log(data);
}
fetchJson.post('https://httpbin.org/post', resource)
.then(handleData)
.catch(console.error);
3) Leverages the Fetch API
browser-fetch-json uses the browser's native Fetch API.
For comparison, the above POST example to create a planet would be done directly using the Fetch API with the code:
const resource = { name: 'Jupiter', position: 5 };
const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify(resource)
};
function handleData(data) {
console.log(data);
}
fetch('https://httpbin.org/post', options)
.then(response => response.json())
.then(handleData)
.catch(console.error);
The examples for browser-fetch-json and the Fetch API each produce the same output.
4) Details
The browser-fetch-json module automatically:
- Serializes the body payload with
JSON.stringify()
. - Adds the JSON data type (
'application/json'
) to the HTTP headers. - Builds the URL query string from the
params
object for GET requests. - Runs
.json()
on the response from the promise. - Sets
credentials
to 'same-origin'
to support user sessions for frameworks/servers such as Grails, Rails, PHP, Flask, etc. - If the response body is HTML or text, it's converted to JSON.
5) API
The format for using browser-fetch-json is:
GET
fetchJson.get(url, params, options).then(callback);
POST
fetchJson.post(url, resource, options).then(callback);
PUT
fetchJson.put(url, resource, options).then(callback);
PATCH
fetchJson.patch(url, resource, options).then(callback);
DELETE
fetchJson.delete(url, resource, options).then(callback);
Notes:
- Only the
url
parameter is required. The other parameters are optional. - The
params
object for fetchJson.get()
is converted into a query string and appended to the url
. - The
resource
object is turned into the body of the HTTP request. - The
options
parameter is passed through to the Fetch API (see the MDN Fetch API documentation for supported init
options).
Dynamic HTTP method
If you need to programmatically set the method, use the format:
fetchJson.request(method, url, data, options).then(callback);
Where method
is 'GET'
, 'POST'
, 'PUT'
, 'PATCH'
, or 'DELETE'
, and data
represents
either params
or resource
.
Logging
Enable basic logging to the console with:
fetchJson.enableLogger();
Pass in a function to use a custom logger or pass in false
to disable logging.
Text to JSON
If the HTTP response body is not JSON (Content-Type
is not "application/json"
or "text/javascript"
), an object containing the body as a string in the bodyText
field is created and passed on through the promise. In addition to the bodyText
field, the object
will have the fields: ok
, status
, statusText
, and contentType
.
For example, an HTTP response for an error status of 500 would be converted to an object
similar to:
{
ok: false,
status: 500,
statusText: 'INTERNAL SERVER ERROR',
contentType: 'text/html; charset=utf-8',
bodyText: '<!doctype html><html><body>Server Error</body></html>'
}
6) Legacy web browsers
To support really old browsers, include polyfills for
Promise and
Fetch API:
<script src=https://cdn.jsdelivr.net/npm/promise-polyfill@8.1/dist/polyfill.min.js></script>
<script src=https://cdn.jsdelivr.net/npm/whatwg-fetch@2.0/fetch.min.js></script>
7) Related
node-fetch-json - A version for node
8) Questions or enhancements
Feel free to submit an issue.
MIT License