Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

gearworks-http

Package Overview
Dependencies
Maintainers
1
Versions
8
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

gearworks-http

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

  • 1.3.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
1
Maintainers
1
Weekly downloads
 
Created
Source

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:

VariableTypeRequiredDescriptionExample
baseUrlstringtrueA base URL string (relative or absolute) that will be used for all requests made with this particular instance."http://localhost:3000"
headersobjectfalseAn object containing headers, e.g. auth headers, that will be sent along with all requests.{ 'header-name': 'custom header value' }
proxyobjectfalseAn Axios proxy config object that will be used for all requests. Useful for debugging requests with e.g. Fiddler{ host: "127.0.0.1", port: 8888}

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.

VariableTypeRequiredDescriptionExample
pathstringtrueThe endpoint path you're making a request to. Will be combined with the baseUrl used in the constructor."foos/123"
methodstringtrueMethod to use for the request. Accepted values are "POST", "PUT", "GET", "DELETE"."POST"
dataobjectfalseObject containing an optional body property with your POST or PUT object and an optional qs property with a querystring parameter object.{ body: { propName: "prop value" }, qs: { paramName: "param value" } }

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. ..."
            ]
        }
    ]
}
VariableTypeRequiredDescriptionExample
bodystringfalseThe response body object or raw string. This may be null!{ message: "Something crazy happened", ... }
axiosResponseAxiosResponsefalseThe Axios response itself, containing the status code and status text. This may be null!{status: 500, statusText: "Internal server error", ...}

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:

VariableTypeDescriptionExample
status_codenumberThe response status code.500
status_textstringThe status text corresponding with the status_code."Internal Server Error".
unauthorizedbooleanIndicates whether the response is a 401 unauthorized response. Automatically set in the ApiError class constructor.false
messagestringA message describing the error."It's treason then."
detailsanyA property set by the BaseClient.parseErrorResponse function that describes extra error details. May be null or undefined.{"sheev": "Are you threatening me, Master Jedi?"}

Keywords

FAQs

Package last updated on 14 Feb 2018

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc