APEye is a jQuery widget for issuing HTTP requests, designed to help document and test APIs. With a few lines of Javascript, you can let users experiment with your API without leaving the documentation. Unlike hurl and apigee, requests are handled entirely by the client – no server-side proxy is needed. Try it out below!
The project is hosted on Bitbucket and is available for use under the MIT software license. You can report bugs and discuss features on the issues page.
Go to the Custom Download page to get the minified JS and CSS. To initialize APEye, call the apeye method on a container element (e.g. <div class="apeye-container"></div>)
$('.apeye-container').apeye({
//options
});
The only CSS properties that must be defined on the APEye container are height and width
.apeye-container {
height: 400px;
width: 800px;
}
If you wish to hide a field or a drop-down choice, simply set display: none on the CSS class for the field/choice. For example, here's how to hide the "Method" field and the "PUT" option of the HTTP method drop-down:
.apeye-container .apeye-method, .apeye-container .method-put {
display: none;
}
| Name | Type | Default | Description |
|---|---|---|---|
| autocompleteMethodSource | null | string | array | function | null | See Method Autocompletion |
| autocompleteUrlSource | null | string | array | function | null | See URL Autocompletion |
| permalinkSender | null | function | null | See Permanent Links |
| permalinkRetriever | null | function | null | See Permanent Links |
| indent | integer | 3 | Indentation used by CodeMirror for the request body. |
| timeout | integer | 5000 | Timeout for requests in miliseconds. |
| autoPrettyPrint | boolean | false | If true, responses will be automatically pretty-printed. If false, a "Pretty Print" button will be shown in the Response header. |
| subdomainTunneling | boolean | false | See Subdomain Tunneling |
| tunnelFilepath | string | "/tunnel.html" | See Subdomain Tunneling |
| permalinkId | string | null | See Permanent Links |
| type | string | "raw" | Setter for the "Type" field. Possible values: raw, json-rpc, xml-rpc, soap11, soap12 |
| httpMethod | string | "post" | Setter for the "HTTP Method" field. Possible values: post, get, put, delete, trace |
| auth | string | "none" | Setter for the "Auth" field. Possible values: none, basic |
| url | string | "" | Setter for the "URL" field |
| method | string | "" | Setter for the "Method" field (only shown if type != "raw") |
| username | string | "" | Setter for the "Username" field (only shown if auth="basic") |
| password | string | "" | Setter for the "Password" field (only shown if auth="basic") |
| id | string | "" | Setter for the "Id" field (only shown if type="json-rpc") |
| body | string | "" | Setter for the request body (only shown if httpMethod = "post" or "put") |
When method autocompletion is enabled via "autocompleteMethodSource", the "Method" field will be turned into a find-as-you-type search box,
and a small arrow will be added to allow viewing all methods.
The "autocompleteMethodSource" option accepts the same values as the JQuery UI "source" option, with one additional feature: if given a string representing a URL to a WSDL file, the file will be immediately requested and parsed, and the autocomplete list will contain the name attributes of each <wsdl:operation> tag contained in it. The example at the top of this page uses this feature with the WSDL file at http://api.apeye.org/soap?wsdl.
As with method autocompletion, using the "autocompleteUrlSource" option will turn the "URL" field into a find-as-you-type search box. The "autocompleteUrlSource" option accepts the same values as the JQuery UI "source" option.
If your API is REST-based, you can have APEye automatically add fields based on parameter names in the URL by enclosing them in angle brackets. For example, if you have the URL "http://example.com/book/<bookId>/foo", a field will be added under the "Request" section with the label "bookId".
If your API endpoint is on a different subdomain as your documentation site, APEye will let you circumvent the same-origin policy by tunneling requests through an iframe. Enabling tunneling is a 3 step processs:
document.domain to a domain suffix shared by both it and the API endpoint. For example, the demo at the top of this page communicates with "api.apeye.org", which shares the "apeye.org" suffix:
document.domain = 'apeye.org';
document.domain to the suffix as above. For example:
<html> <head> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script> <script>document.domain = 'apeye.org';</script> </head> <body></body> </html>
subdomainTunneling option to true
APEye has the ability to serialize the current request and response into a JSON string, and to deserialize such a string to restore all fields to the state represented therein. The permalinkSender, permalinkRetriever and permalinkId options are what facilitate this:
permalinkSender option should be set to a function with the prototype function(jsonData, successCallback) that sends the given jsonData string to an external server (e.g. a pastebin) for storage, and calls successCallback on success with a unique link. This function will be called when the "Link" button, which is only shown if permalinkSender is non-null, is clicked.
permalinkRetriever option should be set to a function with the prototype function(permalinkId, successCallback) that will retrieve the JSON string corresponding to the given permalinkId from the external server, and calls successCallback with that string on success. This function will be called when the permalinkId option is set.