typed-rest-client

What is typed-rest-client?

The typed-rest-client npm package is a lightweight HTTP client library for TypeScript and JavaScript. It provides a strongly-typed interface for making HTTP requests, handling responses, and managing authentication. It is particularly useful for interacting with RESTful APIs in a type-safe manner.

What are typed-rest-client's main functionalities?

HTTP Requests

This feature allows you to make HTTP GET requests to a specified URL and handle the response. The example demonstrates how to create a RestClient instance and make a GET request to an API endpoint.

const { RestClient } = require('typed-rest-client/RestClient');

const client = new RestClient('my-user-agent');

async function getData() {
  let res = await client.get('https://api.example.com/data');
  console.log(res.result);
}

getData();

HTTP POST Requests

This feature allows you to make HTTP POST requests to a specified URL with a payload. The example demonstrates how to create a RestClient instance and make a POST request to an API endpoint with a JSON payload.

const { RestClient } = require('typed-rest-client/RestClient');

const client = new RestClient('my-user-agent');

async function postData() {
  let res = await client.create('https://api.example.com/data', { key: 'value' });
  console.log(res.result);
}

postData();

Authentication

This feature allows you to handle authentication using various methods such as Basic Authentication. The example demonstrates how to create a RestClient instance with Basic Authentication and make a GET request to an API endpoint.

const { RestClient } = require('typed-rest-client/RestClient');
const { BasicCredentialHandler } = require('typed-rest-client/Handlers');

const handler = new BasicCredentialHandler('username', 'password');
const client = new RestClient('my-user-agent', null, [handler]);

async function getData() {
  let res = await client.get('https://api.example.com/data');
  console.log(res.result);
}

getData();

Other packages similar to typed-rest-client

axios

Axios is a popular promise-based HTTP client for the browser and Node.js. It provides a simple and easy-to-use API for making HTTP requests and handling responses. Compared to typed-rest-client, Axios is more widely used and has a larger community, but it does not provide built-in type safety for TypeScript.

node-fetch

Node-fetch is a lightweight module that brings window.fetch to Node.js. It is a minimalistic library for making HTTP requests and handling responses. Compared to typed-rest-client, node-fetch is more lightweight and has a simpler API, but it lacks built-in type safety and advanced features like authentication handlers.

superagent

Superagent is a small progressive client-side HTTP request library. It is flexible and easy to use, with support for various HTTP methods and features like file uploads and authentication. Compared to typed-rest-client, Superagent is more feature-rich but does not provide built-in type safety for TypeScript.

README

Typed Rest and Http Client with TypeScript Typings

A lightweight Rest and Http Client optimized for use with TypeScript with generics and async await.

Status

Stable version 0.15.6 and 1.0 is in preview (npm install typed-rest-client@preview). We expect to release 1.0 very soon.

Features

• Rest and Http Client with typescript generics and async/await/Promises
• Typings included so no need to acquire separately (great for intellisense and no versioning drift)
• Basic, Bearer and NTLM Support out of the box
• Proxy support
• Certificate support (Self-signed server and client cert)
• Redirects supported

Intellisense and compile support from typing the REST calls:

Install the library

stable:

npm install typed-rest-client --save

latest preview:

npm install typed-rest-client@preview --save

Samples

See samples for complete coding examples

Also see rest and http tests for detailed examples.

Errors

http

The http client does not throw unless truly exceptional. A request that successfully executes resulting in a 404, 500 etc... will return a response object with a status code and a body. Redirects (3xx) will be followed by default.

See http tests for detailed examples.

rest

The rest client is a high level client which uses the http client. It's responsibility is to turn a body into a typed resource object.

A 200 will be success.
Redirects (3xx) will be followed.
A 404 will not throw but the result object will be null and the result statusCode will be set.

Other 4xx and 5xx errors will throw. The status code will be attached to the error object. If a restful error object is returned ({ message: xxx}), then the error message will be that. Otherwise, it will be a generic, "Failed Request: (xxx)".

See rest tests for detailed examples.

Contributing

To contribute to this repository, see the contribution guide

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.