gearworks-http v1.3.0

gearworks-http

A standardized HTTP client used by Gearworks apps, backed by Axios. Gearworks is the best way to get started with building Shopify applications!

Installing

You can install this package from NPM with the NPM CLI or with Yarn (recommended):

# With NPM
npm install gearworks-http --save

# With Yarn
yarn add gearworks-http

Importing

You can import the BaseClient via require or TypeScript's import:

// Import with TypeScript or ES6
import BaseClient from "gearworks-http";

// Import via Node's require:
const BaseClient = require("gearworks-http").default;

Usage

This package provides a base, abstract client for you to extend with your own custom logic. When constructing your class, you need to make a call to the base client with super(baseUrl, defaultHeaders?, proxy?), passing along the baseUrl and two other optional variables (documented below) for all requests made by your class.

import BaseClient from "gearworks-http";

export class MyClientClass extends BaseClient {
    constructor() {
        super("http://example.com/api", { 
            "X-Custom-Header-Name": "custom header value sent with each request"
        })
    }

    public getFooObject(id: string) => this.sendRequest<FooType>(`foos/${id}`, "GET");

    public listFooObjects(page: number = 1) => this.sendRequest<FooType>(`foos`, "GET", { 
        qs: {
            page: page
        }
    });

    public createFooObject(foo: FooType) => this.sendRequest<FooType>(`foos`, "POST", { 
        body: foo 
    });

    public updateFooObject(id: string, foo: FooType) => this.sendRequest<FooType>(`foos/${id}`, "PUT", { 
        body: foo 
    });

    public deleteFooObject(id: string) => this.sendRequest<void>(`foos/${id}`, "DELETE");
}

The this.sendRequest<T> function returns a promise that can be awaited when using TypeScript or Babel, and will throw an ApiError when the server responds with a status code that isn't OK.

BaseClient.constructor

The abstract BaseClient class should be extended by your own custom API client classes. When extending the BaseClient, you need to call super() which accepts the following variables:

BaseClient.sendRequest

A protected function that your client class should use to make requests. When using TypeScript, this function accepts a type parameter that can be used to tell the compiler what return type you expect from your request.

This function returns a Promise<T> that can be awaited with TypeScript or Babel. The default implementation will deserialize the response body to an object (type T when using TypeScript) and return it.

You can override this function with your own implementation:

import BaseClient, { RequestData, isOkay } from "gearworks-http";

export class MyClientClass extends BaseClient {
    constructor() {
        super("http://example.com/api", { 
            "X-Custom-Header-Name": "custom header value sent with each request"
        })
    }

    // Override the sendRequest function
    protected async sendRequest<T>(path: string, method: "POST" | "PUT" | "GET" | "DELETE", data: RequestData = { }) {
        // Make your own custom request with this.Axios here.
        const request = this.Axios.request({
            ...
        })
        let result: AxiosResponse;
        let body: any;

        try {
            result = await request;
            body = result.data;
        } catch (e) {
            // Axios was configured to only throw an error when a network error is encountered, not when the server returns a not-OK response.
        }

        if (!isOkay) {
            const error = this.parseErrorResponse(body, result);

            throw error;
        }

        const output: T = ...
        
        return output;
    }
}

BaseClient.parseErrorResponse

A protected function that the client class uses to parse error responses. You shouldn't need to call this function directly unless you're using a custom version of BaseClient.sendRequest<T>. When this function is called, it must return an ApiError – the caller already knows there was an error, it just wants this function to parse it.

The default implementation of this function is configured to parse errors returned by the Gearworks API:

{
    "message": "Something crazy happened", 
    "details": [ 
        {
            "key": "foo",
            "details": [
                "here's an itemized list of everything wrong with this prop",
                "1. ...",
                "2. ..."
            ]
        }
    ]
}

You can override this function with your own implementation, which is particularly useful when you're making requests to a server that isn't using Gearworks:

import BaseClient, { ApiError } from "gearworks-http";

export class MyClientClass extends BaseClient {
    constructor() {
        super("http://example.com/api", { 
            "X-Custom-Header-Name": "custom header value sent with each request"
        })
    }

    protected parseErrorResponse(body?: string | Object, axiosResponse?: AxiosResponse) {
        const statusCode = 66;
        const statusText = "I AM THE SENATE.";
        const message = "It's treason then.";
        const details = {
            "sheev": "Are you threatening me, Master Jedi?"
        }

        const error = new ApiError(66, "I AM THE SENATE", "It's treason then.");
        error.details = details;

        return error;
    }
}

ApiError

The ApiError is a custom Error class that's returned by the BaseClient.parseErrorResponse function and thrown by the default implementation of BaseClient.sendRequest<T> function. It has the following properties: