# apirequest

> API function generator

Latest version **1.0.1** (published 2016-11-01) · ISC license · 0 weekly downloads

## Install

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

## 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.0.1 |
| Published | 2016-11-01 |
| First published | 2016-07-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Bodnar Istvan |
| Maintainers | serif |

## Links

- npm: https://www.npmjs.com/package/apirequest
- Repository: https://github.com/bodnaristvan/apirequest
- Homepage: https://github.com/bodnaristvan/apirequest#readme
- Issues: https://github.com/bodnaristvan/apirequest/issues
- npm.io page: https://npm.io/package/apirequest

## Recent versions

- 1.0.1 (latest) — 2016-11-01
- 1.0.0 — 2016-10-24
- 0.0.4 — 2016-10-24
- 0.0.3 — 2016-07-17
- 0.0.2 — 2016-07-17

## README

# apirequest.js

A tool to help building API libraries. Apirequest allows you to create a library for accessing http services easily, in a centralized way. An API defined by apirequest will return a native Javascript Promise when called, wrapping `fetch` calls.

[![Build Status](https://travis-ci.org/bodnaristvan/apirequest.svg?branch=master)](https://travis-ci.org/bodnaristvan/apirequest)

## Installation
Get the npm module:
```
npm install apirequest --save-dev
```

Since fetch is [not fully supported](http://caniuse.com/#feat=promises) by all browsers it is recommended to use the fetch polyfill from Github:
https://github.com/github/fetch

## Usage
```javascript
// Load the library from npm
import apirequest from 'apirequest';

// Create a new API instance, with optional parameters
const api = new apirequest({
	// The paramTransformer option lets you specify a function that operates on the
	// parameters passed down to the `fetch` request.
	// The function has a single RequestParams argument, allowing you to access the `url`,
	// `params` and `options` properties. The return value must be a RequestParams instance.
	paramTransformer: (request) => {
		// Set a default "maxreturned" parameter on GET queries
		if (request.options.method === 'GET' && !request.params.maxreturned) {
			request.params.maxreturned = 10;
		}
		return request;
	},
	// The responseTransformer option lets you process responses before returning to clients.
	// The function takes the response JSON object as an argument.
	responseTransformer: (response) => {
		// Given this API response envelope:
		// {
		//   meta: { status: 200, ... },
		//   data: { ... }
		// }
		// The following function simply checks the returned status, and returns the wrapped data
		// in the "data" field, or rejects the request promise.
		return (response.meta && response.meta.status === 200) ? response.data : Promise.reject(response);
	}
});
```

Creating the API clients to be distributed can be done using the `get`, `post`, `put` or `delete` methods.

Syntax:
```javascript
get: (url: string, params: Object = {}, options: Object = {}): Function
```

The required `url` parameter is the URL of the API. Placeholders in double curly brackets will be replaced with the values provided by clients.
`params` allows the client library to provide default parameter values. These parameters can be overridden by the user specified values at run-time.
`options` lets the client set request options, these will be passed to `fetch`. This is the good place for specifying custom headers for example.
All parameter of the client can be specified as a JavaScript value or a "thenable" object or function.

```javascript
const getItem = api.get('http://someapi.com/api/item/{{id}}');
const postItem = api.post('http://someapi.com/api/item/');
```

Generated API client functions accept two parameters:
* `params` -- an object containing the request payload
* `options` -- an object setting custom request options (using the fetch API)

The return value is a native JavaScript Promise object, to allow easy processing or further chaining.
Usage:
```javascript
// Get a single item
getItem({id: 1})
	.then((item) => renderItem(item))
	.catch((error) => renderError(error.msg));

// Create a new item
postItem({type: 'item', name: 'Thing'})
	.then((item) => renderSuccess(item))
	.catch((error) => renderError(error.msg));
```

## Examples

### Creating simple clients

#### Define an API client
A simple request to fetch an object from a fixed URL:
```javascript
import apirequest from 'apirequest';
const api = new apirequest();
const getLuke = api.get('http://swapi.co/api/people/1/');

getLuke()
	.then((luke) => console.log(luke))
    .catch((error) => console.error(error));
```

### Working with payload
#### Add user specified payload to the request
Dynamically pass values to the URL:
```javascript
const getPerson = api.get('http://swapi.co/api/people/{{id}}/');

// Called URL will be http://swapi.co/api/people/1/
getPerson({id: 1})
	.then((person) => console.log(person))
	.catch((error) => console.error(error));
```

#### Add default payload to request
```javascript
const getPerson = api.get('http://swapi.co/api/people/{{id}}/', {format: 'wookiee'});

// URL will be http://swapi.co/api/people/1/?format=wookiee
// Note that while `id` was used for the URL generation, the `format` param is passed as
// regular GET query param, as the only remaining payload attribute.
getPerson({id: 1})
	.then((person) => console.log(person))
	.catch((error) => console.error(error));
// Parameter specified at call time will override the default value, the resulting URL
// will be http://swapi.co/api/people/1/?format=json
getPerson({id: 1, format: 'json'})
	.then((person) => console.log(person))
	.catch((error) => console.error(error));
```

#### Add payload async
Parameters and options both can be specified as a JavaScript value, function or Promise.
```javascript
const getPerson = api.get('http://swapi.co/api/people/{{id}}/', {format: 'wookiee'});
// parameter as a function
let personIdByName = (name) => {id: nameToIdMap[name]};
getPerson(personIdByName)
	.then((person) => console.log(person))
	.catch((error) => console.error(error));

// parameter as a Promise
let getPersonIdPromise = new Promise((resolve, reject) => {
	// Get the person ID from a remote server
	if (remoteResponse) {
		resolve({id: remoteResponse.id});
	} else {
		reject('Not found');
	}
});
getPerson(getPersonIdPromise)
	.then((person) => console.log(person))
	.catch((error) => console.error(error));
```

### Response and request processing
#### Process the response
As client functions return with a Promise they can be chained for further processing
```javascript
const getPerson = api.get('http://swapi.co/api/people/{{id}}/');

// Define a method that works with the result
let heightToInches = (person) => {
	person.height = person.height * 0.393701;
	return person;
}
getPerson({id: 1})
	.then(heightToInches)
	.then((person) => {
		console.log(person.name + ' is ' + person.height + ' inches tall');
	})
	.catch((error) => console.error(error));
```

### Handling errors
#### Handle errors
TBD

## Development
See [CONTRIBUTING](./CONTRIBUTING.md)

## Flow support
[Flow](https://flowtype.org/) annotation is not complete yet, will be done later, providing an external type definition.

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