Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cweili/req-json

Promise based simple HTTP/HTTPS client for browser to request JSON or string for RESTful apis, with koa-like middleware support.
https://github.com/cweili/req-json

ajax http https json middleware promise request restful-api weapp wechat wx xhr xmlhttprequest

Last synced: 3 days ago
JSON representation

Promise based simple HTTP/HTTPS client for browser to request JSON or string for RESTful apis, with koa-like middleware support.

Awesome Lists containing this project

README

        

# req-json

[![npm][badge-version]][npm]
[![bundle size][badge-size]][bundlephobia]
[![npm downloads][badge-downloads]][npm]
[![license][badge-license]][license]

[![github][badge-issues]][github]
[![build][badge-build]][workflows]
[![coverage][badge-coverage]][coveralls]

Promise based simple HTTP/HTTPS client for browser to request JSON or string for RESTful apis, with koa-like middleware support.

[Documents and examples](https://req-json.github.io/).

## Installation

### NPM

```
npm install req-json --save
```

```js
import ReqJSON from 'req-json';
```

### Browser

Direct `` include

```html
<script src="https://cdn.jsdelivr.net/npm/req-json@2">
```

### Wechat mini program (weapp)

```js
const ReqJSON = require('req-json/dist/req-json.wx');
```

or just [download](https://cdn.jsdelivr.net/npm/req-json@2/dist/req-json.wx.js) and copy to your project.

## Basic Usage

```js
import ReqJSON from 'req-json';

const reqJSON = new ReqJSON();

reqJSON.get('/api/item/:id', { id: 1 })
.then((item) => {});
```

## Shorthand methods

```js
async getItem(id) {
let item;
try {
item = await reqJSON.get('/api/item/:id', { id });
} catch (err) {
console.error(err);
}
return item;
}

async updateItem(item) {
try {
await reqJSON.post('/api/item/:id', item);
} catch (err) {
console.error(err);
}
}
```

## RESTful API

```js
const resource = reqJSON.resource('/api/item/:id');

async getItem(id) {
let item;
try {
item = await resource.get({ id });
} catch (err) {
console.error(err);
}
return item;
}

async updateItem(item) {
try {
await resource.post(item);
} catch (err) {
console.error(err);
}
}
```

## Methods

Supports `GET` `POST` `PUT` `DELETE` methods.

```js
const resource = reqJSON.resource('/api/item/:id');

async request() {
try {
const response = await resource.get({ id: 1 });
await resource.post({
id: 1,
others: { foo: 'bar' }
});
await resource.put({
id: 1,
others: { foo: 'bar' }
});
await resource.delete({ id: 1 });
} catch (err) {
console.error(err);
}
}
```

## Options

You can set option for ReqJSON instance / resource defination / each single request.

* `headers`: Customized request headers
* `timeout`: Set request timeout

### Set option for ReqJSON instance

```js
const options = {
headers: {
Authorization: 'abc'
},
timeout: 1000
};
const reqJSON = new ReqJSON(options);
```

### Set option for resource defination.

```js
const options = {
headers: {
Authorization: 'abc'
},
timeout: 1000
};
const resource = reqJSON.resource('/api/item/:id', options);

async request() {
try {
await resource.get({ id: 1 });
} catch (err) {
console.error(err);
}
}
```

### Set option for single request.

```js
async request() {
const options = {
headers: {
Authorization: 'abc'
},
timeout: 1000
};
try {
await resource.get({ id: 1 }, options);
} catch (err) {
console.error(err);
}
}
```

## Middlewares

Supports two diffrent kinds of functions as middleware:

* async function
* common function

### Async function ([Can I use](http://caniuse.com/#feat=async-functions))

```js
reqJSON.use(async(context, next) => {
const start = Date.now();
await next();
const ms = Date.now() - start;
console.log(`${context.method} ${context.url} ${ms}ms`);
});
```

### Common function

```js
reqJSON.use((context, next) => {
const start = Date.now();
return next()
.then(() => {
const ms = Date.now() - start;
console.log(`${context.method} ${context.url} ${ms}ms`);
});
});
```

### Context

Context contains these attributes:

```ts
/**
* The path to use for the request, with parameters defined.
*/
path: string

/**
* The HTTP method to use for the request (e.g. "POST", "GET", "PUT", "DELETE").
*/
method: 'POST' | 'GET' | 'PUT' | 'DELETE'

/**
* The URL to which the request is sent.
*/
url: string

/**
* The data to be sent.
*/
data: any

/**
* The options to use for the request.
*/
options: object

/**
* The HTTP status of the response. Only available when the request completes.
*/
status?: number

/**
* The parsed response. Only available when the request completes.
*/
response?: any

/**
* The request headers before the request is sent, the response headers when the request completes.
*/
headers: Headers

/**
* Alias to `headers`
*/
header: Headers

/**
* The original XMLHttpRequest object.
*/
xhr: XMLHttpRequest
```

### Reject when status 4xx or 5xx

#### Async function

```js
reqJSON.use(async(context, next) => {
await next();
if (context.status >= 400) {
throw new Error(context.response);
}
});
```

#### Common function

```js
reqJSON.use((context, next) => {
return next()
.then(() => {
if (context.status >= 400) {
throw new Error(context.response);
}
});
});
```

### Set request headers and get response headers

#### Async function

```js
reqJSON.use(async(context, next) => {
// set request headers
context.headers = {
'If-None-Match': 'abcdefg'
};
await next();
// get response headers
console.log(context.headers.etag);
});
```

#### Common function

```js
reqJSON.use((context, next) => {
// set request headers
context.headers = {
'If-None-Match': 'abcdefg'
};
return next()
.then(() => {
// get response headers
console.log(context.headers.etag);
});
});
```

[badge-version]: https://img.shields.io/npm/v/req-json.svg
[badge-downloads]: https://img.shields.io/npm/dt/req-json.svg
[npm]: https://www.npmjs.com/package/req-json

[badge-size]: https://img.shields.io/bundlephobia/minzip/req-json.svg
[bundlephobia]: https://bundlephobia.com/result?p=req-json

[badge-license]: https://img.shields.io/npm/l/req-json.svg
[license]: https://github.com/Cweili/req-json/blob/master/LICENSE

[badge-issues]: https://img.shields.io/github/issues/Cweili/req-json.svg
[github]: https://github.com/Cweili/req-json

[badge-build]: https://img.shields.io/github/workflow/status/Cweili/req-json/ci/master
[workflows]: https://github.com/Cweili/req-json/actions/workflows/ci.yml?query=branch%3Amaster

[badge-coverage]: https://img.shields.io/coveralls/github/Cweili/req-json/master.svg
[coveralls]: https://coveralls.io/github/Cweili/req-json?branch=master