Constructor

When creating a new instance of APIConnect, you can pass the domain to be used directly as a string, or an options object. Fields in the options object are identical to the instance methods listed below (output is shown in the console).

Returns: Instance

new APIConnect('example');

new APIConnect({ domain: 'example', protocol: 'https', port: '3000' });

connect(route, options)

Connects the route. This is the main workhorse of APIConnect. route is the route to be called, it can have the 4 HTTP verbs GET, POST, PUT, or DELETE preceding it, and it can also contain the format (.json, etc). options is an object that contains the options for the route. Any options here will be merged into the options passed when calling the route. Additionally there are 2 special options: params will "burn in" any parameters so that they will always be passed when the route is called. as will override the resulting method name, which by default is a camel-case form of the human-readable method (get, create, update, or destroy) plus the last fragment in the route. For example, connect('GET friends/statuses') will result in the method name getStatuses.

Returns: Instance

api.connect('friends')

api.connect('POST friends')

api.connect('PUT friends')

api.connect('DELETE friends')

api.connect('friends', { as 'fetchPeople' })

api.connect('search', { params: { complete: true }, as: 'findCompleted' })

contentType(setting)

Gets or sets the contentType. Default is form. If the server requires a special contentType for parameter data, this can be specified here. Currently only form and json are supported. If the content type is "form", the standard key=value parameter serialization format will be used. If the contentType is json, the mime-type will be changed to application/json. In this case params need to be passed as a string, otherwise APIConnect will attempt to stringify them using JSON.stringify, which will fail in older browsers if not available. If you need this functionality a proper JSON shim should be used such as https://github.com/douglascrockford/JSON-js.

Returns: Setting or Instance

api.contentType('json')

api.contentType()

context(name, callback)

Allows a callback inside which the context name will be prepended. If you have multiple routes with the same context, use this so that it doesn't have to be added to every connect statement.

Returns: Nothing

api.context('friends', function() { api.connect('posts'); api.connect('photos'); api.connect('events'); });

cors(setting)

Gets or sets the CORS (cross-origin resource sharing) setting. Default is true. When active, APIConnect will attempt to make cross-browser ajax requests. JSONP will be used instead if the API is not on the same domain and the browser does not support CORS. Setting this to false will turn off CORS support for all browsers. Note that CORS needs to be enabled on the server-side as well. If the API you're trying to connect to does not support this feature it should be turned off.

Returns: Setting or Instance

api.cors(false)

api.cors()

domain(setting)

Gets or sets the domain. The domain can also be set when creating a new instance of APIConnect by passing a string as the first argument to the constructor.

Returns: Setting or Instance

api.domain('graph.facebook.com')

api.domain()

format(dataFormat, appendFormat)

Gets or sets the format. dataFormat is the format passed to the AJAX library. By default this is JSON, so the result will be parsed as JSON. appendFormat is the format appended to each route. By default this is false, so no format will be appended. If true it will use the dataFormat, and if anything else it will use it as the appended format instead.

Returns: Setting or Instance

api.format()

api.format('xml', 'php')

getOverride(setting)

Gets or sets the "getOverride" option. This option turns all POST, PUT, and DELETE requests into GET and instead sets a _method parameter representing the true method. setting can be always, which always adds _method, jsonp, which only overrides when using JSONP, always-except-get, or jsonp-except-get, which do the same except do not override GET methods, which typically do not require a _method parameter.

Returns: Setting or Instance

api.getOverride()

api.getOverride('always')

jsonp(setting)

Gets or sets the JSONP setting. Default is true. When active, APIConnect will attempt to make JSONP requests if CORS is disabled or not available, and if the API is not the same domain. Note that JSONP needs to be enabled on the server-side as well. If the API you're trying to connect to does not support this feature it should be turned off.

Returns: Setting or Instance

api.jsonp(false)

api.jsonp()

option(name, value)

Gets or sets a default option. Default options are merged into the local options of all routes when called, and apply to all connected routes. Instance-wide options are always merged in last, ie. local options will always override them, so they can also be thought of as defaults.

Returns: Setting or Instance

api.option('port', 3000)

api.option('port')

options(obj)

Gets or sets the default options. Calls option for each key/value pair in obj. When called without any arguments returns all default options.

Returns: Setting or Instance

api.options({ port: 3000 })

api.options()

param(name, value)

Gets or sets a default parameter. Default parameters are added to all routes. This is useful for things like API keys or access tokens that need to be used in every API call.

Returns: Setting or Instance

api.param('api_key', 'foo')

api.param('api_key')

params(obj)

Gets or sets the default parameters. Calls param for each key/value pair in obj. When called without any arguments returns all default params.

Returns: Setting or Instance

api.param({ api_key: 'foo' })

api.param()

port(setting)

Gets or sets the port. Default is null.

Returns: Setting or Instance

api.port(3000)

api.port()

postOverride(setting)

Gets or sets the "postOverride" option. Some APIs require a POST method to stand in for PUT and DELETE. This option turns all PUT and DELETE requests into POST with a _method parameter representing the true method. setting can be true or false.

Returns: Setting or Instance

api.postOverride()

api.postOverride(true)

protocol(setting)

Gets or sets the default protocol. Default is "auto". When set to "auto", https will be used if the current page is using https, or if a param like "token", "access_token", or "oauth_token" is found in the params. Otherwise will use http.

Returns: Setting or Instance

api.protocol('https')

api.protocol()

resource(name, options)

Shortcut for connecting multiple routes for the same resource. For singular resources it will connect 4 routes, GET, POST, UPDATE, and DELETE as getName, createName, updateName, and destroyName. For plural routes it will add /:id to the URL and singularize the method name for the above routes, and add an fifth "index" route without the /:id fragment using non-singular method name. Singular/plural routes will attempt to be intelligently detected by finding the singularized form of name. For non-countable or irregular nouns, instead pass { collection: true } in options to force plural routes. Additionally, only and except are allowed in options to limit the routes connected. Both can be either an array or comma-delimited string. Note that when limiting connected routes, index and show are used instead of get to differentiate between singular and plural get routes to be connected. This is only applicable to the resource method.

Returns: Instance

api.resource('tweet')

api.resource('tweets')

api.resource('tweets', { only: 'show,create' })

api.resource('tweets', { except: 'show,create' })

api.resource('equipment', { collection: true })

timeout(setting)

Gets or sets the timeout. Default is 30000. This option will be merged into the params passed to jQuery $.ajax, and tells it when to timeout an ajax request.

Returns: Setting or Instance

api.timeout(10000)

api.timeout()