Browse Source

add motivation behind writing it

tags/v1.0.0-alpha.1
ojizero 1 year ago
parent
commit
618472a735
No account linked to committer's email address
2 changed files with 61 additions and 5 deletions
  1. 58
    2
      README.md
  2. 3
    3
      src/method.ts

+ 58
- 2
README.md View File

@@ -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 View File

@@ -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

Loading…
Cancel
Save