ts-rest-client

ts-rest-client is a small and simple package for consuming RESTful Services. It allowes you to retrieve typed response data very easily and independently from the client implementation.

An Example using the Axios RestClient implementation

ts-rest-client comes with an implemenation using axios.

For this example we assume that you want to consume a RESTful Service that allows you to retrieve cars. We also assume that the resource is exposed at http://localhost:8080/api/cars. Here is the type definition of a car:

interface Car {
    name: string;
    brand: string;
}

1. Create a RestResource class

First we need to create a class that inherits from RestResource, which specifies the available requests. We implement a method called getCars for retrieving all cars:

class CarRestResource extends RestResource {

    getCars = (): Promise<Car[]> => {
        return this.get({
            url: 'http://localhost:8080/api/cars'
        });
    }
}

We expect to retrieve an array of cars, thus we specify Promise<Car[]> as return type. We call this.get() and pass an request-object as the only paremeter. Here´s the definition of the GetRequest object:

interface GetRequest {
    url?: string;
    headers?: Header[];
}

2. Create an Axios client:

const restClient = new AxiosRestClient();

3. Create an instance of CarRestResource and pass the client

const carRestResource = new CarRestResource(restClient);

4. Use your RestResource

carRestResource.getCars().then(
    (cars) => { // cars now is of type Car[]
        const firstCar = cars[0]; //car is of type Car
        console.log(firstCar.name);
    }
)

Using baseUrl and basePath

AxiosRestClient allows you to specify the baseUrl of your server. In your RestResource class you can specify the basePath of your resource:

const restClient = new AxiosRestClient('http://localhost:8080'); // baseUrl

class CarRestResource extends RestResource {

    protected basePath = '/api/cars'; // basePath

    getCars = (): Promise<Car[]> => {
        return this.get();
    }

    getCar = (carId: number): Promise<Car> => {
        return this.get({
            url: `/${carId}`
        });
    }
}

const carRestResource = new CarRestResource(restClient);

As a result, when you call carRestResource.getCars() the url of the request is going to be baseUrl + basePath + request.url: http://localhost:8080/api/cars. And for carRestResource.getCar(1) the url is going to be: http://localhost:8080/api/cars/1.

This separation of baseUrl and basePath only makes sense if you plan to use multiple RestResource classes.

class CustomerRestResource extends RestResource {
    
    basePath = '/api/customers';

    getCustomers = (): Promise<Customer[]> => {
        return this.get();
    } 
}

const customerRestResource = new CustomerRestResource(restClient); // we use the same restClient as for CarRestResource

customerRestResource.get(); // http://localhost:8080/api/customers