An XHR Cross Origin Proxy allows you to make XHR requests to different friendly API services.
A YuzuJS production
XCOP (XHR Cross Origin Proxy) allows you to make XHR requests to different friendly API services.
- Serve the site from the same origin as the web services, which may mean unnecessarily serving HTTPS images and CSS. ex: https://api.example.com (Boo, hiss)
- Use CORS. But this limits you to GET and POST and does not allow you to set headers.
- Use a reverse proxy server on the domain that served your html file. This can be, in some cases, dificult to setup, and is slower than hitting the destination server directly. Plus it leaves the information in the clear on the first leg of it's journey (i.e. not HTTPS).
With XCOP you can effectively make cross origin XHR requests with full verbs (not only GET and POST but also PUT, DELETE, PATCH, etc). You can also set HTTP headers to your heart's content. Simply place a simple HTML file on the friendly cross origin server (yes, you need access to the server). Under the covers, XCOP package will load this into an iframe and communicate with it via PostMessage. You will need a fairly modern browser.
$ npm install xcop
XCOP us easy to use. Just call xcop with the origin that you would like to communicate with (xcop.html must be in the root of the cross origin server). XCOP will return a Q promise that is fulfilled with an XHR object.
The XHR object accepts a request object that consists of the following:
- url - the url that you would like to hit, relative to the origin.
- headers - an object with key/value pairs.
- method - the HTTP method (default = "GET").
- body - a string containing optional data sent in a POST or PUT.
It returns a promise that is fulfilled with a response object. The response object contains the following:
- status - the HTTP status reponse (ex: 200 for "OK")
- body - the body of the response
- headers - a response header object with key/value pairs.
Let's say that you have a web page that is loaded from http://www.example.com, but you need to post some data to https://api.example.com (i.e. not on the same origin). The code below will show you how to do so.
var xcop = require"xcop";var origin = "";xcoporigindonevar request =url: "/items/123"headers: "content-type": "application/json"method: "PUT"body: JSONstringifyid: 123 name: "new name";xhrrequestdoneconsole.logresponsestatus + " " + responsebody;console.error"Something went wrong." errmessage;;console.errorerrmessage;;
You can also see XCOP in action, live, on the Interwebs! Check out this fiddle. http://jsfiddle.net/donavon/6tozto6v/
Instead of opening your web service up to other websites, you may now "white list" which origins are allowed to access your server.
To do so, edit the
xcop.html file served by the destination server. By default, XCOP allows access from any origin.
var whiteList = ;
To setup a whitelist, replace the
whiteList array with the list of your allows origins.
In our example above, you may chose to only allow http://www.example.com to use your api.
If so, your
xcop.html file will read:
var whiteList = "";
You may choose to use different
xcop.html files with different white lists for development, QA, and production.
Q. I'm getting the error "XCOP is unavailable".
A. You likely have not setup xcop.html in the root of the origin server that you are hitting with XCOP. In the example above, that would be https://api.example.com/xcop.html
Q. How cool is XCOP?
For use under MIT license