@frui.ts/apiclient
v1.0.0-rc.4
Published
Frui.ts helpers for HTTP communication
Downloads
330
Readme
@frui.ts/apiclient
Frui.ts provides a simple abstraction for issuing backend calls.
Please note that you are not forced to use this library, and you may make network calls from your repositories (or elsewhere) any way you want.
IApiConnector
IApiConnector
is an abstraction for making actual HTTP requests. It provides raw functions (get
, post
, put
, patch
, delete
) as well as their counterparts that serialize the content (postObject
, putObject
, patchObject
, deleteObject
).
FetchApiConnector
The default implementation FetchApiConnector
uses window.fetch
for network requests, JSON.stringify
as a serializer, and a middleware that handles other than 2xx response status codes as errors by default.
The default middleware is called handleErrorStatusMiddleware
and throws FetchError
when the status code is other than 2xx.
You can provide custom implementations of the fetch function, serializer, and middleware through the constructor. You can also customize content-type header.
If you want to use another HTTP client library such as Axios, you should implement the IApiConnector
interface with a custom class AxiosApiConnector
that would just translate the interface functions to Axios calls.
Also, if your backend uses XML, you should provide custom serializer and customize the contentType
constructor parameter.
Usage
// creating new FetchApiConnector with default behavior
const connector = new FetchApiConnector();
// FetchApiConnector with custom fetch function
import { fetch as fetchPolyfill } from "whatwg-fetch";
const connector = new FetchApiConnector({ fetchFunction: fetchPolyfill });
// FetchApiConnector with a custom middleware
function middleware(response: Response) {
if (response.status >= 500 && response.status < 600) {
throw "Server error";
} else {
return response;
}
}
const connector = new FetchApiConnector({ middleware });
RestRequestBuilder
RestRequestBuilder
helps to compose URLs and properly serialize and deserialize the payload. It is a stateful object that mutates its inner URL. It uses the provided apiConnector
to make the actual network call.
It provides three types of requests:
a. Entity calls
The request payload is serialized and the response payload is deserialized to the specified entity type:
get<T>(queryParams?: any): Promise<T>;
post<T>(content: any): Promise<T>;
put<T>(content: any): Promise<T>;
patch<T>(content: any): Promise<T>;
b. Request only calls
The request payload is serialized but the response is not touched.
getRaw(queryParams?: any): Promise<Response>;
postOnly(content: any): Promise<Response>;
putOnly(content: any): Promise<Response>;
patchOnly(content: any): Promise<Response>;
delete(content?: any): Promise<Response>;
c. Custom calls
You can provide custom payload for the request, response payload is not touched.
postData(data?: BodyInit): Promise<Response>;
putData(data?: BodyInit): Promise<Response>;
patchData(data?: BodyInit): Promise<Response>;
Usage
const builder = new RestRequestBuilder(apiConnector, "www.base.url", {});
const invoices = await builder.path(`customers/${customerId}/invoices/${invoiceId}`).get<Invoice[]>(); // GET to www.base.url/customers/123/invoices
builder.reset();
// you can also use fluent url builder
const fluentInvoices = await builder.one("customers", 123).all("invoices").get<Invoice[]>(); // GET to www.base.url/customers/123/invoices
builder.reset();
const users = await builder.all("users").post<User[]>({ foo: "bar" }); // POST to www.base.url/users with content { foo: "bar" }
// Bearer token in the header for all requests
const requestParams: RequestInit = {
headers: { authorization: "Bearer xxxyyyzzz" },
};
const builder = new RestRequestBuilder(apiConnector, "www.base.url", requestParams);