anyfetch
v2.1.11
Published
AnyFetch API wrapper for Node.js
Downloads
28
Readme
AnyFetch API wrapper for Node.js
You'll only be interested in this package if you want to create client applications for AnyFetch.
If you're interested in creating a Hydrater or a Provider, you may find AnyFetch Hydrater Library and AnyFetch Provider Library more high level, and easier to work with.
This npm
package makes communicating with the AnyFetch servers easy for clients. Check out the full API documentation.
Basic usage example
var AnyFetch = require('anyfetch');
var anyfetchBasic = new AnyFetch('LOGIN', 'PASSWORD');
// OR
var anyfetch = new AnyFetch('TOKEN');
anyfetch.getUser(function(err, user) {
console.log('Hello, my name is ' + user.name);
};
Access authentication
AnyFetch delivers long lived
access_token
, so you don't need to use arefresh_token
.
Both Basic
and Bearer
authentication schemes are supported. The getToken
method makes it easy to retrieve a token from the user's credentials.
If you're using Bearer
authentication, the token in use is available in the property anyfetch.accessToken
.
var AnyFetch = require('anyfetch');
var anyfetchBasic = new AnyFetch('LOGIN', 'PASSWORD');
// Retrieve token from credentials (GET /token)
anyfetchBasic.getToken(function(err, res) {
if(err) {
throw err;
}
anyfetch = new AnyFetch(res.body.token);
// We now access the Fetch API using Bearer authentication
// You can get back the token by accessing `anyfetch.accessToken`
console.log('We are using the token ' + anyfetch.accessToken);
};
OAuth
The getAccessToken
static function helps you obtain an access_token
during the OAuth flow.
AnyFetch.getAccessToken('APP_ID', 'APP_SECRET', 'OAUTH_VERIFICATION_CODE', function(err, accessToken) {
var anyfetch = new AnyFetch(accessToken);
});
Basic endpoint to function mappings
This library provides a function per API endpoint. A full reference card is available.
We adopt the following naming convention:
verbEndpointName(function(error, result) {})
Callbacks are expected to be of the form: function(err, result)
. result
is a Response
object from Superagent.
Note that some endpoints yield a result with empty body (e.g. POST /company/update
).
Examples:
getUsers(cb)
will callGET /users
postCompanyUpdate(cb)
will callPOST /company/update
postUser({ email: '[email protected]' }, cb)
deleteCompanyReset(cb)
will callDELETE /company/reset
deleteCompanyReset(cb, { force: true })
will callDELETE /company/reset?force=true
deleteToken(cb)
will callDELETE /token
Example usage:
var anyfetch = new AnyFetch('TOKEN');
anyfetch.getDocuments({ search: 'John' }, function(err, res) {
if(err) {
throw err;
}
var docs = res.body;
console.log('Got these documents:', docs)
});
Some functions expect an id
or identifier
:
getDocumentById(id, cb)
will callGET /documents/{id}
getDocumentByIdentifier(identifier, cb)
will callGET /documents/identifier/{identifier}
Some other endpoints are expressed relative to a document. For example, GET /documents/{id}/raw
refers to the document with id {id}
.
For the sake of clarity, we provide the following two-steps call syntax:
getDocumentById(id).getSimilar(cb)
will callGET /documents/{id}/similar
getDocumentById(id).getRaw(cb)
will callGET /documents/{id}/raw
getDocumentById(id).postFile(config, cb)
will callPOST /documents/{id}/file
Note that the first function does not take any callback. It is simply responsible for building the first part of the request, which is then carried out when calling the sub-function.
A full description of the mapping functions is available in api-descriptors.json
.
Posting a file associated to a document
Head's up: if you need to post a new document along with a file, see below for the sendDocumentAndFile
helper function.
The function getDocumentById(id).postFile(config, cb)
expects a config
hash containing at least a file
key from which to obtain the file. It can be a string (path to the file) or a ReadStream
. It can also contains contentType
(MIME type) and filename
keys.
config
can also be passed as a function. In this case, it is invoked with a callback, which must be called with (err, config)
.
Example usage:
var deliverConfig = function(cb) {
cb(null, {
file: fs.createReadStream('path/to/file.png'),
filename: 'doge.png'
});
};
getDocumentById(id).postFile(deliverConfig, function(err) {
// Handle error if any
});
Utility functions
anyfetch.js
provides higher level utility functions. They cover classic use-cases that would otherwise require several API calls. When possible, calls are grouped in a single batch call.
Batch request
Make several GET
calls in a single request. It takes a map associating the endpoint to its parameters.
var pages = {
'/users': null,
'/documents': {
search: 'Marc'
}
};
anyfetch.batch(pages, function(err, res) {
// Handle err
var users = res.body['/users'];
var documents = res.body['/documents'];
});
See GET /batch for details.
Create a subcompany
When creating a subcompany, we usually want to create its first admin, and migrate it into the new subcompany. The function createSubcompanyWithAdmin
allows you to do this automatically.
The created user will be an admin in the new subcompany.
Your callback is called with err
, subcompanies
(info about the newly created company) and admin
(info about its admin).
var subcompany = {
name: 'the_fake_subcompany',
hydraters: [
'http://plaintext.hydrater.anyfetch.com/hydrate',
'http://pdf.hydrater.anyfetch.com/hydrate',
]
};
var admin = {
email: '[email protected]',
name: 'Chuck Norris',
password: 'no_need'
};
anyfetch.createSubcompanyWithAdmin(subcompany, admin, function(err, company, admin) {
console.log('Company ' + company.id + ' has been created, with ' + admin.id + ' as its admin');
});
Get information about the current user
This function allows you to retrieve the user's info from its credentials (login / password or token).
anyfetch.getUser(function(err, user) {
console.log('Hello, my name is ' + user.name);
};
Send a document with a file in a single call
When writing an AnyFetch provider, it is very common to need to create a document on the AnyFetch API, and post an associated file right away. This function makes it easy to do just that:
var doc = {
document_type: 'file',
data: {
foo: 'some_string'
},
metadata: {
some_key: 'some random sentence'
}
};
// We'll simply upload from filename
var fileConfig = {
file: __dirname + '/../test/samples/hello.jpg',
filename: 'hello_image',
contentType: 'image/jpeg'
};
anyfetch.sendDocumentAndFile(doc, fileConfig, function(err, doc) {
console.log('The document has been posted');
});
For details about the supported fileConfig
options, see the postFile
function above.
Manager endpoints
A few endpoints of the AnyFetch Manager are available in anyfetch.js
for convenience.
The first example is
getToken(cb)
, described above.postAccountName(accountName, cb)
allows you to associate an account name to the access token currently in use. It can only be used with Bearer auth.getAvailableProviders(options, cb)
allows you to obtain a list of all the available providers. Theoptions
object can have booleanstrusted
andfeatured
to restrict the list.options
can be omitted. Example:var anyfetch = new AnyFetch('access_token'); anyfetch.getAvailableProviders({ trusted: true }, 'my_awesome_account_name', function(err, res) { console.log('Here are all the trusted providers:'); console.log(res.body); });
Overriding target URLs
By default, all methods target the production URLs: https://api.anyfetch.com and https://manager.anyfetch.com respectively. There are two ways to override that:
For all instances:
var AnyFetch = require('anyfetch'); AnyFetch.setApiUrl('http://localhost:3000'); AnyFetch.setManagerUrl('http://localhost:3000');
For one instance only:
var AnyFetch = require('anyfetch'); var anyfetch = new AnyFetch('TOKEN'); anyfetch.setApiUrl('http://localhost:3000'); anyfetch.setManagerUrl('http://localhost:3000');
It is very useful when writing tests and want to take advantage of the mocking server described below.
Test framework
anyfetch.js
provides a ready-to-run mock server based on Restify. It may be useful to test apps that use the AnyFetch API.
The mock server is created with AnyFetch.createMockServer()
and started with server.listen(port, cb)
. It is a simple Restify server.
Once the server is running, override the AnyFetch API url to make it point to your localhost
with anyfetch.setApiUrl(url)
. If you're using the OAuth helper method AnyFetch.getAccessToken
, override the manager URL as well with AnyFetch.setManagerUrl(url)
. Indeed, the mock server also plays the role of manager.
Example: starting the mock server on port 1337
var AnyFetch = require('anyfetch');
var server = AnyFetch.createMockServer();
var port = 1337;
var apiUrl = 'http://localhost:' + port;
server.listen(port, function() {
console.log('AnyFetch mock server running on ' + apiUrl);
AnyFetch.setApiUrl(apiUrl);
AnyFetch.setManagerUrl(apiUrl);
done();
});
Mocks
The mock server will serve static JSON files from the folder node_modules/anyfetch/lib/test-server/mocks
. You can tailor them to your need. You can generate those JSON files at any time by:
- Setting the
LOGIN
andPASSWORD
environment variables to your Fetch API credentials - Running
node node_modules/anyfetch/bin/make-mocks.js
Overriding
At any point, you can specify which JSON content to serve for any endpoint using the following methods:
server.override(verb, endpoint, json)
to start serving your custom JSON for this endpointserver.restore(verb, endpoint)
to go back to the default built-in responseserver.restore()
to restore all previously overriden endpoints
Note that these will work even if you try to override an endpoint which does not exist by default. It is useful in testing, for example if you have an odd request to send to a specific route on another API.