It's fork of apiapi
In this fork
- Updated all dependencies
- Added ESM version
- Added request limiter for Axios (Default is 7 RPS)
- Added
http-build-queryfor build correct query params (e.g. now allow nested objects) - Add query and body payload from field in params (set param as string, instead string[],see example below)
Api client for lazy devs
Quickly write up any json api client for your purpose.
You can use both callbacks and promises for api client methods.
Last update
Here is a partial of ApiClient options:
{
methods: {
posts: 'GET /posts/{userId}?limit={limit}',
postsAdd: 'PUT /posts/{postId}',
},
query: {
// posts: ['limit', 'userId'], // old solution work too
posts: 'queryParams', // now you can set field for query params
postsAdd: ['postId'],
},
body: {
postsAdd: 'payload', // now you can set field for req body
}
}Make GET request:
const payload = {
userId: 1,
limit: 5,
queryParams: {
offset: 3,
filter: {
id: [1,2]
}
}
}
const resp = await client.posts(payload)
// Will exec with url:
// 'https://.../posts/1?offset=3&filter%5Bid%5D%5B0%5D=1&filter%5Bid%5D%5B1%5D=2'Now for POST/PUT/PATCH
const putPayload = {
postId: 3,
payload: {
id: 3,
title: 'foo',
body: 'bar',
userId: 1,
}
}
const resp = await client.postsAdd(putPayload)
// Will exec with:
const reqOpts = {
method: 'PUT',
url: 'https://jsonplaceholder.typicode.com/posts/3',
responseType: 'json',
headers: {},
data: { id: 3, title: 'foo', body: 'bar', userId: 1 } } }
}Now don't need to create any transformRequest, and set all payload fields by default lib behavior.
Enjoy =)
Installation
npm install @1xtr/apiapiImport
// ES5 example
const ApiClient = require('1xtr/apiapi')
// ES6+ example
import { ApiClient } from '1xtr/apiapi'Example usage
Sample api client for github
const ApiClient = require('1xtr/apiapi')
const github = new ApiClient({
baseUrl: 'https://api.github.com',
// Set rate limit
rateLimitOptions: { maxRPS: 7 },
// Define api methods
methods: {
issues: 'get /repos/{user}/{repo}/issues',
},
// Github api requires proper user-agent to work
headers: {
'user-agent':
'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.91 Safari/537.36',
},
})
// will request https://api.github.com/repos/boo1ean/casual/issues?state=closed and return json data
github.issues({ user: 'boo1ean', repo: 'casual', state: 'closed' }).then(console.log)
// also you can use custom headers for each request
github
.issues({ user: 'boo1ean', repo: 'casual', state: 'closed' }, { headers: { Authentication: 'token GITHUB-TOKEN' } })
.then(console.log)Call methods passing callbacks
// Call method with params
github.issues({ user: 'boo1ean', repo: 'casual', state: 'closed' }, function (err, result) {
// process result
})
// Call method without params
github.issues(function (err, result) {
// process result
})Transform response
You can specify response transform function:
// Will transform all methods responses (global transform)
new ApiClient({
// ...
transformResponse: function transformResponse(res, body, requestParams) {
// res - request's response object
// body = response body
// requestParams = object passed to called method
},
})
// transform response of specific method
new ApiClient({
// ...
methods: {
issues: 'get /issues',
},
transformResponse: {
issues: function parseIssues(res, body, requestParams) {
return body.slice(0, 5)
},
},
})Transform request
You can decorate request params and headers with transformRequest hooks.
// params - object passed to method
// requestBody - object which will be used as request body
// opts - additional request options (e.g. headers)
var client = new ApiClient({
transformRequest: function transformRequest(params, requestBody, opts) {
// You should return overrides for given objects
opts.headers = { 'x-some-header': 'header-value' }
return [params, requestBody, opts]
},
})Also you can perform method-specific transformRequest hook:
new ApiClient({
transformRequest: {
issues: function transformParams(params) {
// ...
},
},
})If you want to create async request transformer, just return a promise
new ApiClient({
transformRequest: {
issues: function transformParams (params) {
return new Promise(...);
}
}
});Pick specific params for query string
var client = new ApiClient({
methods: {
issues: 'get /repos/{user}/{repo}/issues',
},
query: {
// Will pick only these params for issues method and omit all others
issues: ['state'],
},
})
// will request https://api.github.com/repos/boo1ean/casual/issues?state=closed
client.issues({ custom: 'custom param', user: 'boo1ean', repo: 'casual', state: 'closed' })Pick specific params for request body
var client = new ApiClient({
methods: {
createSomething: 'post /something',
},
body: {
// Only title will be picked from method params and passed to request body
createSomething: ['title'],
},
})Response type
By default response type is json but you can change it if you want to one of arraybuffer, blob, document, json, text.
new ApiClient({
// ...
responseType: 'text',
})Set error handler
Global error handler
var client = new ApiClient({
errorHandler: function errorHandler(result) {
console.log('API error response status code %s', result.status)
},
})method-specific error handlers:
var client = new ApiClient({
errorHandler: {
getIssues: function handleGetIssuesError(res) {
console.log('Get issues error response status code %s', result.status)
},
},
})Params validation
You can declare list of required params for methods
var client = new ApiClient({
methods: {
createIssue: 'post /issues'
},
required: {
createIssue: ['name', 'body', 'author_id']
}
});
// Automatically asserts params object for having required attrs
client.createIssue({...});Raw response body
By default response body is expected to be json and will be automatically parsed, to get raw body use flag:
var client = new ApiClient({
// ...
rawResponse: true,
})Debug
To see debug output just run you script like this:
DEBUG=apiapi node script.js
Debug output is provided by debug
Changelog
See CHANGELOG.md
License
MIT
