README
node-sdk
Official NodeJS Client for the PortaText API.
Documentation
- Autogenerated documentation for this source can be found in the doc directory.
- The endpoint tests should also serve as good doucmentation on how to use the API.
- General PortaText documentation (including the REST API) can be found at the PortaText wiki.
Installing
Add this library to your package.json configuration:
"dependencies": {
"portatext": "latest"
}
Basic use
Getting a client instance
The first thing is to get a Client instance, for example the Curl implementation:
var portatextMod = require('portatext');
var portatext = new portatextMod.ClientHttp();
(Optional) Set your logger
You can optionally set a Console compatible logger:
portatext.setLogger(console);
By default, the client will use the NullLogger.
Authenticating
You can authenticate to the endpoints by using your API key or your username/password. This translates to either doing this:
portatext.setApiKey(apiKey);
Or this:
portatext.setCredentials(username, password);
When you specify a username and password instead of an api key, the sdk will automatically login and get a session token when needed.
Using the endpoints
All the API commands can be found in the command/api directory. The client offers a way to instantiate them by just calling them by their name.
Quick example
As an example, to create a template, you would do:
client
.templates() // Get an instance of the Templates endpoint.
.text("The text of my template")
.description("My first template")
.name("template1")
.post() // Call the Templates endpoint with a POST.
.then(function (result) {
// Handle result...
})
.catch(function (err) {
// Handle error...
});
To get a template by id:
client.templates().id(45).get().then(function (result) { .... });
Or, to get all the templates:
client.templates().get().then(function (result) { .... });
The result
Calling an endpoint will return a Promise. On fulfillment,
a result object is returned (see below for how to handle it). On rejection, you can get a string
or
a result object (in case the request was made but the server returned one or more errors in its response,
for example if a field was missing or different than what was expected).
Testing for success
if (result.success) {
...
}
Getting error strings back from the server
if (result.errors) {
result.errors.forEach(function (error) {
...
});
}
Getting data back from the server
if (result.success) {
var data = result.data;
}
Developers
This project uses standard npm scripts. Current tasks include:
- test: Runs Mocha tests.
- jsdoc: Runs JSDoc3.
- eslint: Runs ESLint.
- coverage: Runs the tests and then Instanbul to get a coverage report.
- build: This is the default task, and will run all the other tasks.
Running a phing task
To run a task, just do:
npm run build
Contributing
To contribute:
- Make sure you open a concise and short pull request.
- Throw in any needed unit tests to accomodate the new code or the changes involved.
- Run
npm run build
and make sure everything is ok before submitting the pull request (make eslint happy). - Your code must comply with the Javascript Standard Style, ESLint should take care of that.
- If your code is accepted, it will belong to PortaText and will be published under the Apache2 License.
License
The source code is released under Apache 2 License.
Check LICENSE file for more information.