API-ify

This helper library lets you easily create express-driven APIs that you can call easily on the client side. For example, on the server you create the code to be API-ified (this sample is written in ES6/7: it makes use of ES7's async/await functionality):

import apiify from 'apiify'
import express from 'express'

let app = express()
app.use('/api', apiify({
  sayHello(name = 'World') {
    // `this` in this context is the request object
    return 'Hello ' + name
  },

  delayed() {
    // `this` in this context is the request object
    return Promise((yes, no) => {
        setTimeout(() => yes('All done')), 1000)
    })
  }
}))

app.get('/', (req, res) => res.end('My other route...'))
app.listen(/* some port */)

Then, in the client JS, you create an API-client (in this case with a base-URL of '/api'), and it will automatically expose the methods in an object:

import apiClient from 'apiify/client'

window.onload = async function() {
  let api = await apiClient('/api')

  //
  // now I can call API-methods in a few forms:
  //
  // 1)
  let helloDevelopers = await api('sayHello', 'developers!')
  //
  // 2)
  let helloDevelopers2 = await api.sayHello('developers!')
  //
  // 3)
  let allDone = await api.delayed()
}

Installing

npm install apiify

API of apiify (server-module)

The apiify server-side library has one, default export with the following signature:

function apiify(methods) : express.Router

Where methods is a dictionary (object) of functions. Functions in this dictionary may (if chosen) return promises (if they're asynchronous in nature). Each method will have its this variable bound to the current request object when called.

API of apiify/client (browser-module)

The preferred way to use this module is to require it in (e.g., you will need to use a tool like Webpack/browserify/etc. to bundle it with your app). When requiring, It exports one function with the following signature:

async apiClient(baseUrl) : ApiClient

baseUrl is the base-url to use when making requests

The ApiClient that this returns also sets convenience methods: one for each method that is defined on the server. That is, if the server defines an API with a method named sayHello(...), then the ApiClient returned by this method will have a method like:

async function sayHello(...) {...}

Which will automatically call the one on the server-side, passing parameters through the request.

ApiClient

An ApiClient is a function with the following signature:

async function(methodName, ...args) : Any

Including with <script ...></script>

To include the client-side API using HTML script tags, just download and include the build/client.js file in this repository (available after building the source). When included, the async apiClient(baseUrl) : ApiClient function (discussed above) is accessible via apiify.client(...). For example:

<script src="/path/to/client.js"></script>
<script>
apiify.client('/api')
.then(function(api) {
  // now use 'api' like, for example:
  api.sayHello()
  .then(function(msg) {
    console.log(msg)
  })
})
</script>

License

Copyright (c) 2015, Jonathan Apodaca Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.