Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: about 1 month ago
JSON representation
Promise based simple HTTP/HTTPS client for browser to request JSON or string for RESTful apis, with koa-like middleware support.
- Host: GitHub
- URL: https://github.com/cweili/req-json
- Owner: Cweili
- License: mit
- Created: 2017-07-19T11:43:11.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-23T21:36:03.000Z (3 months ago)
- Last Synced: 2024-10-30T14:18:52.752Z (about 2 months ago)
- Topics: ajax, http, https, json, middleware, promise, request, restful-api, weapp, wechat, wx, xhr, xmlhttprequest
- Language: JavaScript
- Homepage: https://req-json.github.io/
- Size: 157 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
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