@brr-dev/api
v1.0.9
Published
A base API controller written in Typescript with handy generics and easy inheritance.
Downloads
627
Readme
api
A simple wrapper around the Fetch API that provides automatic JSON request/response handling and generic typing.
Installation
You can easily add the public package to any Node project:
# npm
npm install @brr-dev/api
# yarn
yarn add @brr-dev/api
Usage
It's recommended to create a module for the API calls you need, and to preconfigure any APIs that need authorization or have a base URL.
// /src/data/fakeSite/fakeAPI.js
export const fakeAPI = api.create({
baseURL: "https://fake.site",
headers: { Authorization: "Bearer FakeTokenFakeToken-FakeTokenFakeToken" },
});
// /src/data/fakeSite/trees.js
export function getTrees(options) {
return fakeAPI.get("/v1/trees", options);
}
export function addTrees(newTrees, options) {
return fakeAPI.post("/v1/trees", newTrees, options);
}
// /src/data/fakeSite/index.js
export * as trees from "./trees.js";
export { fakeAPI as api } from "./fakeAPI.js";
// /src/data/index.js
export * as FakeSite from "./fakeSite";
Then you can use it pretty simply, with decent namespacing:
import { FakeSite } from "/src/data";
const theTrees = await FakeSite.trees.getTrees();
Public Methods
.fetch(path, options)
This method does most of the work of our wrapper.
- It builds the URL for the request based on options and configuration
- It parses and encodes request and response body JSON
- It converts a custom
query
option to a proper query string
The standard
fetch()
already includes abody
property on the request object, but we just add another layer of handling. If thebody
property you pass in is not a string, then thebody
will be replaced with a JSON string of itself, and thecontent-type
header will be set toapplication/json
.
Instead of having to build the URL query string yourself (eg. "?date=2024-01-01), you can pass it to the
query
property on the options object:// This will add "?date=2024-01-01" to the URL api.fetch("/fake", { query: { date: "2024-01-01" }, });
We also have the following public methods, which are just wrappers around the API's .fetch()
method, but with default HTTP methods set. Notice that some of them also include a second "body" argument.
.get(path, options)
.post(path, body, options)
.put(path, body, options)
.patch(path, body, options)
.delete(path, options)
All of these public
.fetch()
methods have generic type parameters so that you can optionally add more type safety to your request and response data. For example, if I'm doing a post request where I'm sending updated objects, and I'm expecting an array of all of the object ids as a response, I could create a helper function like this in my data module:type MyObject = { id: number; name: string }; function updateObjects(...newObjects: MyObject[]) { return api.post<MyObject[], number[]>("/fake/site", newObjects); }
.create(config)
Create a new api object with all the same methods from a given configuration object. The configuration object can specify default headers
and a default baseURL
.
const DemoAPI = api.create({
baseURL: "https://fake.site",
headers: {
Authorization: `Bearer FakeToken-FakeToken-FakeToken`,
},
});
// GET https://fake.site/v1/fake (w/ Authorization header)
await DemoAPI.get("/v1/fake");
Public Properties
methods
Constants for HTTP methods.
Protected Properties and Methods
protected _baseURL: string
This is the configured base URL for the API. This will be used as the base and combined with any passed-in path
values to create the full request URL. Defaults to an empty string.
protected _getURL(path, query, baseURL): string
This is the method that builds the URL of the fetch request from the various bits of config. This includes any values passed to baseURL
, path
, and query
.
protected _cleanupStr(str): string
A helper method that strips whitespace and trailing/leading "/" characters from the URL parts so we can build our URLs predictably and consistently.