Doctape will retire its service as of November 25th
For more information about the service's shut down visit www.doctape.com
This library manifests a javascript module providing asynchronous method calls against doctapes API.
The latest stable release is available via npm install doctape.
Just include distrib-browser/doctape.js in your web project.
When creating a single-page javascript app that should use the Doctape API, you create a new Doctape-object using the configuration from the Doctape Developer Center.
After that, you can call the method use, passing it a function that will be bound to the Doctape object once it retrieved a valid access token. In that function you are able to make resource method calls:
Doctape({
appType: 'client',
appId: '6ca7209c-9250-4073-a927-700d9ccbce33',
callbackURL: 'http://localhost:8000/examples/client.html',
scope: ['docs', 'account']
}).run(function () {
this.getAccount(function (acc) {
document.write('Welcome, ' + acc.username + '!');
});
});
The available resource methods are documented in the sub-section Resource Methods.
If you are, for any reason, building a client-type app which is not a single-page javascript app (but really - you shouldn't) and/or already retrieved your token via the Implicit Grant OAuth flow, you can instead of run use the useToken method like this:
Doctape({
appType: 'client',
appId: '6ca7209c-9250-4073-a927-700d9ccbce33',
callbackURL: 'http://localhost:8000/examples/client.html',
scope: ['docs', 'account']
}).useToken(implicit_grant_access_token, function () {
this.getAccount(function (acc) {
// …;
});
});
When using this library in a Server-Type app, you'll first create a Doctape-object from the config you received in the Doctape Developer Center:
var dt = Doctape({
appType: 'server',
appId: 'a6015f8e-9f62-4d08-80fe-8969c53f566b',
appSecret: '6767689e-2f64-4575-b364-37956ca0cda9',
callbackURL: 'http://example.org/',
scope: ['docs', 'account']
});
After that, you have to redirect your users to the URL stored the objects authURL property. Through that, your flow will continue on the page pointed to by the callbackURL parameter, retrieving as url query part an authorization code. Using that code, you call the method useCode, passing it a function that will be bound to the Doctape object once it retrieved a valid access token. In that function you are able to make resource method calls:
dt.useCode(authorization_code, function () {
this.getAccount(function (acc) {
// …;
});
});
You'll find more information concerning the JSON object structures in the Doctape Developer Center.
To each method you pass specific arguments and one or two callback functions. If the first callback argument is not null, it will get passed the data upon a successful request. Should this request fail, the second callback argument is called with the error, or and exception is thrown if the second callback argument is non-existent. If the first callback argument is null, the second callback argument is expected to accept two node-style arguments (err, data).
getAccount (cb...)passes the callback a JSON structure containing the account data of the currently logged-in user.getAvatar (cb...)passes the callback a string of binary image data representing the users avatar.
getDocumentList (cb...)passes the callback a JSON object containing a list of all documents.getDocumentListWithMetadata (cb...)passes the callback a JSON object containing a list of all documents, enriched with metadata.
getDocumentInfo (id, cb...)passes the callback a JSON structure with information about the document given byid.setDocumentInfo (id, info, cb...)sets the informationinfoof the document given byid, passes the callback the updated information as a JSON object.setDocumentTags (id, tags, cb...)sets the tags of the document given byidto the listtags, passes the callback the updated information as a JSON object.setDocumentName (id, name, cb...)sets the name of the document given byidto the string given byname, passes the callback the updated information as a JSON object.getDocumentOriginal (id, cb...)passes the callback binary data representing the original data of the document given byid.getDocumentThumbnail (id, cb...)passes the callback binary data representing a thumbnail (jpg, 120px) of the document given byid.getDocumentThumbnailLarge (id, cb...)passes the callback binary data representing a thumbnail (jpg, 320px) of the document given byid.cloneDocument (id, cb...)clones the document given byid, passes the callback a JSON object containing the cloned documents id.setDocumentPublicState (id, state, cb...)sets the published-state of the document given byidto true/false according tostate, passes the callback a JSON object containing the new state and the public url.publishDocument (id, cb...)publishes the document given byid, passes the callback a JSON object containing the new public state and the public url.unpublishDocument (id, cb...)unpublishes the document given byid, passes the callback a JSON object containing the new public state and the public url.deleteDocument (id, cb...)deletes the object given byid, passes the callback a JSON object indicating the success.extractArchiveContents (id, cb...)extracts the contents of the archive-type document given byid, passes the callback a JSON object indicating the success.
In case the authorization fails, the function registered as onauthfail will be called:
var dt = Doctape(…);
dt.onauthfail = function () {…};
There exist several test for the basic infrastructure and OAuth authentication. You launch these by running mocha (together with should.js) inside the top directory. You need to insert valid credentials and a valid authorization code into test.js to make all tests pass successfully.
To build the library for npm, just run make node from inside the top directory. You'll find the npm package structure in distrib-node.
To build a javascript file, run make browser and then require distrib-browser/doctape.js from your web page.
To build a javascript file to include alongside jQuery, run make jquery and then require distrib-browser/doctape.jquery.js from your web page.
The library consist of a core module, and several platform-dependent wrappers, currently for Node.JS and Browsers supporting jQuery.
The core-module (DoctapeCore in core.js) contains the infrastructure for authenticating with the doctape OAuth server and then performing authorized calls against the API.
This (DoctapeSimple in simple.js) is currently the main interface to the code module, providing methods for easily working with the resources provided by the Doctape API.
Platform-dependent wrappers (wrapper-*.js, currently only wrapper-node.js, wrapper-browser.js and wrapper-browser-jquery.js) enrich the simple- and core-modules with an event-infrastructure providing methods for emitting, and (un)subscribing from, events as well as a method for performing HTTP(S) requests.
When using this library on a platform which is neither of the two, it is easy to write and plug-in another submodule. See section Contributing for more information.
We gladly accept Issues as well as Pull Requests via our GitHub Repository.
The current set of methods mapping to resources on our API is incomplete. A documentation of all our API resources can be found in the doctape devcenter.
When creating a new wrapper-method one uses the methods getResource, postResource and deleteResource all of which accept a string indicating API endpoint (i.e. /doc) and a callback function in the form of (function cb (err, data)). When the callback is called, the data may be JSON.parsed and, if the field data.error is not set, the data can be evaluated.
The structure of the JSON data can be examined in the doctape devcenter, also.
A wrapper should subclass the DoctapeSimple module and add its specific methods as mixins into the core.env object.
See wrapper-node.js and wrapper-browser.js for examples.