apeman-api

apeman-api
==========

[![Build Status][bd_travis_shield_url]][bd_travis_url]
[![Code Climate][bd_codeclimate_shield_url]][bd_codeclimate_url]
[![Code Coverage][bd_codeclimate_coverage_shield_url]][bd_codeclimate_url]
[![npm Version][bd_npm_shield_url]][bd_npm_url]
[![JS Standard][bd_standard_shield_url]][bd_standard_url]

[bd_repo_url]: https://github.com/apeman-cmd-labo/apeman-api
[bd_travis_url]: http://travis-ci.org/apeman-cmd-labo/apeman-api
[bd_travis_shield_url]: http://img.shields.io/travis/apeman-cmd-labo/apeman-api.svg?style=flat
[bd_travis_com_url]: http://travis-ci.com/apeman-cmd-labo/apeman-api
[bd_travis_com_shield_url]: https://api.travis-ci.com/apeman-cmd-labo/apeman-api.svg?token=
[bd_license_url]: https://github.com/apeman-cmd-labo/apeman-api/blob/master/LICENSE
[bd_codeclimate_url]: http://codeclimate.com/github/apeman-cmd-labo/apeman-api
[bd_codeclimate_shield_url]: http://img.shields.io/codeclimate/github/apeman-cmd-labo/apeman-api.svg?style=flat
[bd_codeclimate_coverage_shield_url]: http://img.shields.io/codeclimate/coverage/github/apeman-cmd-labo/apeman-api.svg?style=flat
[bd_gemnasium_url]: https://gemnasium.com/apeman-cmd-labo/apeman-api
[bd_gemnasium_shield_url]: https://gemnasium.com/apeman-cmd-labo/apeman-api.svg
[bd_npm_url]: http://www.npmjs.org/package/apeman-api
[bd_npm_shield_url]: http://img.shields.io/npm/v/apeman-api.svg?style=flat
[bd_standard_url]: http://standardjs.com/
[bd_standard_shield_url]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg

Remote api call

Installation
-----

Install apeman-api module via [npm][npm_url].
``bash
$ npm install apeman-api -g
`


[npm_url]: https://www.npmjs.com/

Usage
---------

1. Prepare an Apemanfile.js at your project root.
2. Run the command via CLI.

Apemanfile.js
`javascript
/* Example of Apemanfile.js /

'use strict'

const co = require('co')

module.exports = {
$cwd: __dirname,
$pkg: { / ... / },
$proto: [ / ... / ],
$api: {
// Define APIs
'sign': {
signin (username, password) {
return co(function * () { // Returns a promise
/ ... /
return { success: true }
})
},
signout () {
/ ... /
}
}
}
}

`

Then, start the server with command

`bash
$ apeman-api
`

Client Script
`javascript
#!/usr/bin/env

'use strict'

const apemanApiClient = require('apeman-api/client')
const co = require('co')

co(function * () {
let api = apemanApiClient('http://localhost:3000')

{
// Access to sign api
let sign = yield api.connect('sign')
// Call defined method with promise interface.
let { success } = yield sign.signin('my-account', 'a9!ladsf0')
/ ... /
}
}).catch((err) => console.error(err))

`

##### CLI Options

`bash
$ apeman-api -h

Usage: apeman-api [options]

Remote api call

Options:

-h, --help output usage information
-V, --version output the version number
-p, --port Port number
-c, --configuration Pathname of Apemanfile

Examples:

$ apeman-api -p 3000 # Start apeman api server


`

Programmatic API
---

apeman-api also provide programmatic API.

Firstly, install the module locally.

`bash
$ npm install apeman-api --save-dev
`

Then,

`javascript
#!/usr/bin/env

'use strict'

const apemanApi = require('apeman-demo-api')
const co = require('co')

co(function * () {
yield apemanApi({})
}).catch((err) => console.error(err))

`


##### Programmatic Options

| Key | Description | Default |
| --- | ----------- | ------- |
| port | Port number | |
| configuration | Pathname of Apemanfile | |

Advanced Usage
---------

This is a more advance example of apeman api.

Names starts with $ and @ has special meaning and not treated as api module.

Apemanfile.js
`javascript
/* Example of Apemanfile.js /

'use strict'

const co = require('co')

module.exports = {
$cwd: __dirname,
$pkg: { / ... / },
$proto: [ / ... / ],
get $api () {
const sign = require('apeman-api-sign')
const session = require('apeman-api-middleware-session')
const debug = require('debug')('my-project:api')
const { db } = this.$ctx
return {
// Define APIs
'sign': sign(),
// Called before method invocation
$before () {
const s = this
let { module, method, params } = s.state.invocation
debug(${module}.${method} with params: ${params})
},
// Called after method invocation
$after () {
let s = this
let { module, method, returns } = s.state.invocation
debug(${module}.${method} with returns: ${returns})
},
// Koa middlewares
$middlewares: [
session(db.models.Session)
],
// You can define custom scope with @ prefix
'@admin': {
user: {
destroy (id) { / ... / }
}
}
}
}
}

``

License
-------
This software is released under the MIT License.

Links
------

+ [apeman][apeman_url]
+ [apeman-cmd-labo][apeman_cmd_labo_url]

[apeman_url]: http://github.com/apeman-labo/apeman
[apeman_cmd_labo_url]: http://github.com/apeman-cmd-labo