gangway

Gangway

A client-side API abstraction layer.

Gangway is our general purpose tool for working with APIs on the client-side. It is a thin layer on top of superagent with specific opinions related to how we work.

Usage

Gangway is a factory function that progressively layers configuration options for building an AJAX request with superagent.

The first step is invoke Gangway with some options:

var Gangway = require('gangway')

var API = Gangway({
  baseURL: 'http://example.com',
  headers: {
    'x-api-key': 'your-token-for-every-request'
  }
})

With default configuration options out of the way, let's add some specific routes.

API.route({
  users: {
    read: {
      method : 'GET',
      path   : '/users/{id?}' // ? indicates that the parameter is optional
    }
  }
})

API.users.read() will now perform a GET request to /users/{id}. The ? in the path option specifies that it is optional. This is useful when using the same route for index and show endpoints for resources.

For RESTful resources, adding routes this way can become tedious. Gangway provides another method for quickly building routes for RESTful resources:

// This is equivalent to creating a create, read, update, and destroy
// route. Options are folded into every route.
API.resource("comments", {})

From there, the Gangway instance is ready for use!

// This will send a request to GET http://example.com/users
API.users.read()

// This will send a request to GET http://example.com/users/10
API.users.read({ params: { id: '10' } })

// The same is true for routes added via API.resource
API.comments.read({ params: { id: '2' }})

Documentation

See the available options below, or consider working through the Hello Gangway guide.

Available options

baseURL    : The base URL prepended to all requests
body       : The request body
headers    : Request headers,
method     : Request method (GET, POST, PUT, PATCH, DELETE, etc...)
beforeSend : Configure an instance of superagent before the request is sent
onResponse : Run before resolving a request to preprocessing data
onError    : Run before rejecting a request to preprocessing errors
params     : Populate bindings in paths and are sent as request bodies. Defaults to body.
path       : The path fragment of the endpoint, appended to baseURL
type       : Content type, defaults to JSON
query      : An object of query parameters. Gangway will automatically stringify this into the URL.

Additionally consider skimming through the ./docs folder.

---

Visit code.viget.com to see more projects from Viget.