APIConnect is a Javascript class that provides a simple way to interact with APIs, specifically those hosted on other domains. Setup is as simple as creating the instance, specifying the domain, connecting the route, and running it. APIConnect works in all major browsers with jQuery as its only dependency, and is now available on npm!
Any route can have any number of params in the base URL (contexts). These contexts are always optional, and will only be added if they exist in the params object when the route is called.
Once the route is connected, calling it is as simple as calling a camelized method on the instance. When making the call, the first argument is the params object, and the second argument is for "options". Here you can specify options for both APIConnect as well as any valid option for jQuery.ajax, meaning all standard callbacks will work.
API calls also pass back jQuery deferred objects, so these can be used as well.
Both params or options can also be made "global" or instance-wide by specifying them directly on the instance. They will be applied to all routes (but can be overwritten with local params/options).
The 4 main HTTP verbs, "GET", "POST", "PUT", and "DELETE", are allowed in routes, and map to humanized verbs "get", "create", "update", and "destroy", respectively. "GET" is the implied default.
This code is actually posting to a live Facebook page through APIConnect!
The camelized method name is a combination of the humanied HTTP verb and the last non-parameter fragment in the route. In the examples, a "non-parameter fragment" is photos as opposed to a "parameter fragment" :photo_type, etc. If no non-parameter fragments exist, the last parameter fragment will be used instead.
If this is still not good enough, the entire method name can easily be overridden using the as option when connecting the route.
Params can also be "burned in" when connecting routes, allowing even more expressive statements.
"resource" serves as a shortcut to all 4 HTTP verbs.
Members of these routes can be limited using only and exclude.
If a resource is a collection, passing collection: true in the options for "resource" will create standard collection routes including an "index" method.
If collection is omitted, it will attempt to be intelligently detected by the pluralization of the resource passed.
Options are passed in when making the call, and can be overridden there, however instance-wide options are set on the object itself.
Additionally the basic options "domain", "protocol", "port", "timeout", "cors", and "jsonp" can be set directly on the instance. When setting options, the instance itself will be returned, allowing method-chaining just like jQuery objects.
All such options are both getters and setters. Passing no arguments will return their current value.
APIConnect will by default attempt to use CORS (cross-origin resource sharing). For this to work, the API you're working with needs to be sending the correct response headers. If your calls are returning a 200-level response but no data is coming in, most likely CORS is not supported and needs to be disabled.
Turning off CORS support will fall back to JSONP, which also needs to be enabled on the API side.
Certain older browsers (earlier versions of IE, etc) do not support CORS. In this case, APIConnect will fall back to JSONP if the request is on another domain. This means that if both CORS and JSONP are enabled on the API server, all browsers will work with APIConnect of the box. However if JSONP is not supported, the request must be on the same domain or it will fail outright.
If you have many routes with the same context you can hold onto it so as not to repeat yourself.
Results from an api call can be cached locally for the duration of the page load. Only GET requests will be cached and only if the params match exactly. If cached, the calls will resolve successfully immediately.