浏览代码

add motivation behind writing it

tags/v1.0.0-alpha.1
ojizero 2 年前
父节点
当前提交
618472a735
没有帐户链接到提交者的电子邮件
共有 2 个文件被更改,包括 61 次插入5 次删除
  1. 58
    2
      README.md
  2. 3
    3
      src/method.ts

+ 58
- 2
README.md 查看文件

@@ -6,10 +6,64 @@

</div>

## Motivation

> Inspired when developing an internal API client in my company [Yamsafer](https://github.com/Yamsafer) :heart:, and by the design of the [Cloudflare NodeJS client](https://github.com/cloudflare/node-cloudflare) :heart:.

This library aims to simplify the creation of HTTP API clients by providing a declarative abstraction of HTTP requests.

Instead of worrying about how to consume some HTTP API, we should focus on the buisness logic behind this API call, so instead of worrying about whether the HTTP request library uses promises, or callbacks, or how the response object is formated, you simply declare what you want, and move on with your life.

So instead of having the focus be centered around how you make the request like the following,

```javascript
import request from 'request' // or who knows what you wanna use ¯\_(ツ)_/¯

function myApiWrapper (arg1, arg2) {
return new Promise((resolve, reject) => {
request(
`https://some.api/some/url/${arg1}/some-resource/${arg2}`,
/*other options who knows,*/
(error, response, data) => {
if (error) reject(error)

resolve(response) // or data ¯\_(ツ)_/¯
}
)
})
}

/// TOO MUCH BOILERPLATE !!
```

The above boilerplate where you worry about whether you're using `request` or `request-promise` or whatnot, and you worry about ho to resolve your response and what it looks like, get completely abstracted and unified into,

```javascript
import portal from '@ojizero/portal'

const portalBase = portal({ baseUrl: 'https://some.api' })

const myApiWrapper = portalBase.route({ path: '/some/url/:arg1/some-resource/:arg2' })

/// Woosh done :D
```

And you gain the consistent response structure (placed inside a promise). This can be extended even further into building entire clients for you APIs!

It also adds support for standardized validation for request arguments, query strings, and payload (provided using [Joi](https://github.com/hapijs/joi) :heart:)

## Installation

With NPM

```
npm i -S @ojizero/portal
```

Or if you're into Yarn

```
npm install --save @ojizero/portal
yarn add @ojizero/portal
```

## Usage
@@ -38,6 +92,8 @@ const someGetMethodPromise = YourAPIClient.someGetMethod() // GET http://some.ba
const someGetMethodWithParamPromise = YourAPIClient.someGetMethodWithParam(5) // GET http://some.base.url/some/path/5
```

Examples can be found in the [`examples`](./examples) folder

## API Documentation

### (default export) createPortalClient(config)
@@ -142,7 +198,7 @@ This is still a work in progress :D any help is appreciated
### TODO

- [ ] Finish documentations
- [ ] Why?
- [x] Why?
- [ ] More on external API
- [ ] Support non JSON payload
- [ ] Get `onError: resolve` to work

+ 3
- 3
src/method.ts 查看文件

@@ -26,8 +26,8 @@ export interface MethodSpec {
export type RouteFunction = (...args: any[]) => Promise<Response>
export type MethodFactory = (spec: MethodSpec) => RouteFunction

export function method (client: Client): MethodFactory {
return function methodGenerator (spec: MethodSpec): RouteFunction {
export function methodGenerator (client: Client): MethodFactory {
return function methodFactory (spec: MethodSpec): RouteFunction {
const {
path,
method: _method = 'GET',
@@ -129,4 +129,4 @@ export function method (client: Client): MethodFactory {
}
}

export default method
export default methodGenerator

正在加载...
取消
保存