Преглед на файлове

add motivation behind writing it

ojizero преди 2 години
No account linked to committer's email address
променени са 2 файла, в които са добавени 61 реда и са изтрити 5 реда
  1. 58
  2. 3

+ 58
- 2
README.md Целия файл

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


## 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,

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

function myApiWrapper (arg1, arg2) {
return new Promise((resolve, reject) => {
/*other options who knows,*/
(error, response, data) => {
if (error) reject(error)

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


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,

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 {
method: _method = 'GET',
@@ -129,4 +129,4 @@ export function method (client: Client): MethodFactory {

export default method
export default methodGenerator