fetch-json
    TypeScript icon, indicating that this package has built-in type declarations

    2.5.0 • Public • Published

    fetch-json

    logos

    A wrapper around Fetch just for JSON (written in TypeScript)

    License:MIT npm Size Vulnerabilities Build

    Why would you fetch anything but json? ;)

    1) Make REST Easy

    fetch-json automatically:

    1. Converts the HTTP response to JSON if it's not already JSON (especially convenient for HTTP errors)
    2. Serializes the body payload with JSON.stringify()
    3. Adds the application/json HTTP header to set the data type
    4. Appends the GET params object items to the URL
    5. Runs .json() on the response
    6. Sets credentials to 'same-origin' (support user sessions in Grails, Rails, PHP, Django, Flask, etc.)

    fetch-json is ideal for a JAMstack architecture where "dynamic programming during the request/response cycle is handled by JavaScript, running entirely on the client".

    2) Setup

    Web browser

    In a web page:

    <script src=fetch-json.min.js></script>

    or from the jsdelivr.com CDN:

    <script src=https://cdn.jsdelivr.net/npm/fetch-json@2.4/dist/fetch-json.min.js></script>

    Node.js server

    Install package for node:

    $ npm install node-fetch fetch-json

    and then import:

    import { fetchJson } from 'fetch-json';

    or for older CommonJS modules use:

    const { fetchJson } = require('fetch-json');  //deprecated

    3) Examples

    HTTP GET

    Fetch the NASA Astronomy Picture of the Day:

    // NASA APoD
    const url =    'https://api.nasa.gov/planetary/apod';
    const params = { api_key: 'DEMO_KEY' };
    const 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:

    // Create Jupiter
    const resource = { name: 'Jupiter', position: 5 };
    const handleData = (data) =>
       console.log('New planet:', data);  //http response body as an object literal
    fetchJson.post('https://httpbin.org/post', resource)
       .then(handleData)
       .catch(console.error);

    For more examples, see the Mocha specification cases:
    spec/node.js (Mocha output for each build under Run npm test)

    To see a website that incorporates fetch-json, check out DataDashboard:
    data-dashboard.js.org 📊

    4) Examples Using async/await

    HTTP GET

    Fetch the NASA Astronomy Picture of the Day:

    // NASA APoD
    const show = async () => {
       const url =    'https://api.nasa.gov/planetary/apod';
       const params = { api_key: 'DEMO_KEY' };
       const data =   await fetchJson.get(url, params);
       console.log('The NASA APoD for today is at: ' + data.url);
       };
    show();

    HTTP POST

    Create a resource for the planet Jupiter:

    // Create Jupiter
    const create = async (resource) => {
       const data = await fetchJson.post('https://httpbin.org/post', resource);
       console.log('New planet:', data);  //http response body as an object literal
       };
    create({ name: 'Jupiter', position: 5 });

    5) Leverages the Fetch API and node-fetch

    fetch-json calls the native Fetch API if in a web browser and calls node-fetch if running on node.

    For comparison, the above POST example in section 2 to create a planet would be done calling the Fetch API directly with the code:

    // Create Jupiter (WITHOUT fetch-json)
    const resource = { name: 'Jupiter', position: 5 };
    const options = {
       method: 'POST',
       headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
          },
       body: JSON.stringify(resource),
       };
    const handleData = (data) =>
       console.log(data);  //http response body as an object literal
    fetch('https://httpbin.org/post', options)
       .then(response => response.json())
       .then(handleData)
       .catch(console.error);

    The example with fetch-json and the example without fetch-json each produce the same output.

    6) API

    API — HTTP Request

    The format for using 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:

    1. Only the url parameter is required.  The other parameters are optional.
    2. The params object for fetchJson.get() is converted into a query string and appended to the url.
    3. The resource object is turned into the body of the HTTP request.
    4. The options parameter is passed through to the Fetch API (see the init documentation on MDN).
    5. options is enhanced with a boolean setting for strictErrors mode (default false) that throws an error to .catch() whenever the HTTP response status is 400 or higher.

    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.

    API — Logging

    Enable basic logging to the console with:

    fetchJson.enableLogger();

    To use a custom logger, pass in a function that accepts 9 parameters to log. To disable logging, pass in false.

    To get an array containing the names of the parameters:

    fetchJson.getLogHeaders();

    The default console output looks like:
    2018-09-12T07:20:12.372Z – "request" - "GET" – "api.nasa.gov" – "https://api.nasa.gov/planetary/apod"
    2018-09-12T07:20:13.009Z – "response" - "GET" – "api.nasa.gov" – "https://api.nasa.gov/planetary/apod" - true - 200 - "OK" - "application/json"

    7) Response Text Converted to JSON

    The HTTP response body is considered to be JSON if the Content-Type is "application/json" or "text/javascript".  If the HTTP response body is not JSON, fetch-json passes back through the promise an object with a bodyText string field containing response body text.

    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 lang=en><body>Server Error</body></html>',
    }

    With fetch-json, you know the response body will always be passed back to you as a simple object literal.

    8) Base Options

    Use fetchJson.setBaseOptions() to configure options to be used on future fetchJson requests.

    The example below sets the Authorization HTTP header so it is sent on the subsequent GET and DELETE requests:

    fetchJson.setBaseOptions({ headers: { Authorization: 'Basic WE1MIGlzIGhpZGVvdXM=' } });
    fetchJson.get('https://dnajs.org/api/books/').then(displayBooks);  //with auth header
    fetchJson.delete('https://dnajs.org/api/books/1001');              //with auth header

    To have multiple base options available at the same time, use the FetchJson class to instantiate multiple copies of fetchJson:

    import { FetchJson } from 'fetch-json';
    const fetchJsonA = new FetchJson({ headers: { From: 'aaa@example.com' } }).fetchJson;
    const fetchJsonB = new FetchJson({ headers: { From: 'bbb@example.com' } }).fetchJson;
    fetchJsonA.get('https://dnajs.org/api/books/').then(displayBooks);  //from aaa@example.com
    fetchJsonB.delete('https://dnajs.org/api/books/1001');              //from bbb@example.com

    9) TypeScript Declarations

    The TypeScript Declaration File file is fetch-json.d.ts in the dist folder.

    The declarations provide type information about the API. For example, the fetchJson.post() function returns a Promise for a FetchResponse:

    fetchJson.post(url: string, resource?: RequestData,
       options?: FetchOptions): Promise<FetchResponse>

    10) 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.2/dist/polyfill.min.js></script>
    <script src=https://cdn.jsdelivr.net/npm/whatwg-fetch@3.5/dist/fetch.umd.min.js></script>

    Note: JSDOM does not include fetch, so you need to add a polyfill.  See usage of whatwg-fetch in spec/jsdom.js and gulpfile.js.

    10) Contributor Notes

    To be a contributor, fork the project and run the commands npm install and npm test on your local clone.  Make your edits and rerun the tests.  Pull requests welcome.



    "Stop trying to make fetch happen without #fetchJson!"

    Feel free to submit questions at:
    github.com/center-key/fetch-json/issues

    MIT License

    Install

    npm i fetch-json

    DownloadsWeekly Downloads

    897

    Version

    2.5.0

    License

    MIT

    Unpacked Size

    33.1 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar
    • avatar