rest-client
A TypeScript rest api client based on node-fetch with type assertion.
Install
yarn add @vpriem/rest-client
Basic usage
import { RestClient } from '@vpriem/rest-client';
interface Payload {
id: string;
}
const client = new RestClient('https://my.api');
await client.get<Payload>('/resource/{id}', { params: { id: 1 } });
This will perform a GET https://my.api/resource/1
request.
Advanced usage
You can define your own client by extending the RestClient
class in order to map your resources with methods and return types:
import { RestClient } from '@vpriem/rest-client';
interface BlogPost {
id: string;
title: string;
}
class BlogApi extends RestClient {
async getPost(id: string): Promise<BlogPost> {
return this.get<BlogPost>('/post/{id}', { params: { id } });
}
}
Now you can instantiate a client and send requests:
const blogApi = new BlogApi('https://blog.api');
await blogApi.getPost('859e3470-bcaa-499d-948f-0216e168e633');
This will perform a GET https://blog.api/post/859e3470-bcaa-499d-948f-0216e168e633
request.
For a complete client example see here.
API
import { RestClient } from '@vpriem/rest-client';
new RestClient(url: string, options?: Options): RestClient
Instantiate a rest client.
-
url
the base url -
options?.headers
the default headers to send along with every request
async RestClient.request<R = object>(path: string, options?: FetchOptions): Promise
Perform a basic request.
-
path
path of the endpoint e.g/post/{id}
-
options?.headers
headers to send with the request, overriding default headers -
options?.params
path parameters to replace in the path -
options?.query
query object, will be encoded and appended to the url -
options?.body
body object, will be JSON encoded. AContent-Type: application/json
header will be added to the request
async RestClient.get<R = object>(path: string, options?: FetchOptions): Promise
Perform a GET
request.
async RestClient.post<R = object>(path: string, options?: FetchOptions): Promise
Perform a POST
request.
async RestClient.put<R = object>(path: string, options?: FetchOptions): Promise
Perform a PUT
request.
async RestClient.delete<R = object>(path: string, options?: FetchOptions): Promise
Perform a DELETE
request.
RequestError
The request error thrown for http status < 200 or ≥ 300.
-
RequestError.message
http status text -
RequestError.status
http status code -
RequestError.response
node-fetch response
Helpful to handle 404 for example:
class BlogApi extends RestClient {
async getPost(id: string): Promise<BlogPost | null> {
try {
returnn await blogApi.getPost(id);
} catch (error) {
if (error instanceof RequestError && error.status === 404) {
return null;
}
throw error;
}
}
}