# apiapi

> Create api clients for node and browser with ease

Latest version **1.7.1** (published 2016-07-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install apiapi
pnpm add apiapi
yarn add apiapi
bun add apiapi
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.7.1 |
| Published | 2016-07-04 |
| First published | 2015-01-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Known vulnerabilities | 0 (+29 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Egor Gumenyuk |
| Maintainers | boo1ean |
| Keywords | api, client, xhr, ajax, rest, fetch |

## Links

- npm: https://www.npmjs.com/package/apiapi
- Repository: https://github.com/boo1ean/apiapi
- Issues: https://github.com/boo1ean/apiapi/issues
- npm.io page: https://npm.io/package/apiapi

## Dependencies (5)

- [axios](https://npm.io/package/axios.md) ^0.7.0
- [debug](https://npm.io/package/debug.md) ^2.2.0
- [lodash](https://npm.io/package/lodash.md) ^3.10.1
- [bluebird](https://npm.io/package/bluebird.md) ^3.0.2
- [shitty-qs](https://npm.io/package/shitty-qs.md) ^1.0.1

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.7.1 (latest) — 2016-07-04
- 1.7.0 — 2016-02-21
- 1.6.1 — 2016-01-22
- 1.6.0 — 2015-12-28
- 1.5.1 — 2015-12-27
- 1.5.0 — 2015-12-27
- 1.4.0 — 2015-12-26
- 1.3.0 — 2015-11-03
- 1.2.1 — 2015-10-30
- 1.2.0 — 2015-10-29
- 0.8.0 — 2015-09-06
- 0.7.1 — 2015-09-01
- 0.7.0 — 2015-09-01
- 0.6.1 — 2015-08-27
- 0.6.0 — 2015-08-20
- … 13 more at https://npm.io/package/apiapi/versions

## README

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

## Installation

```bash
npm install apiapi
```

## Example usage

Sample api client for github

```js
var ApiClient = require('apiapi');

var github = new ApiClient({
	baseUrl: 'https://api.github.com',

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

```javascript
// 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:

```js
// 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.

```javascript
// 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:

```javascript
new ApiClient({
	transformRequest: {
		issues: function transformParams (params) {
			// ...
		}
	}
});
```

If you want to create async request transformer, just return a promise

```javascript
new ApiClient({
	transformRequest: {
		issues: function transformParams (params) {
			return new Promise(...);
		}
	}
});
```

## Pick specific params for query string

```javascript
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

```javascript
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`.

```javascript
new ApiClient({
	// ...
	responseType: 'text'
});
```

## Set error handler

Global error handler

```javascript
var client = new ApiClient({
	errorHandler: function errorHandler (result) {
		console.log('API error response status code %s', result.status);
	}
});
```

method-specific error handlers:

```javascript
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

```javascript
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:

```javascript
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](https://github.com/visionmedia/debug)

## Changelog

See [CHANGELOG.md](CHANGELOG.md)

## License

MIT

---
_Source: https://npm.io/package/apiapi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._