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.

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. Extensible handlers for others.
• Proxy support
• Certificate support (Self-signed server and client cert)
• Redirects supported

Intellisense and compile support:

Install

npm install typed-rest-client --save

Or to install the latest preview:

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

Samples

See the samples for complete coding examples. Also see the 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. Its 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.

Debugging

To enable detailed console logging of all HTTP requests and responses, set the NODE_DEBUG environment varible:

export NODE_DEBUG=http

or

set NODE_DEBUG=http

Node support

The typed-rest-client is built using the latest LTS version of Node 8. We also support the latest LTS for Node 4 and Node 6.

Contributing

To contribute to this repository, see the contribution guide

To build:

$ npm run build

To run all tests:

$ npm test

To just run unit tests:

$ npm run units

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.

Security Issues

Do you think there might be a security issue? Have you been phished or identified a security vulnerability? Please don't report it here - let us know by sending an email to [e-mail].