- Notifications
You must be signed in to change notification settings - Fork54
JS Library for the Particle API
License
particle-iot/particle-api-js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
JS Library for the Particle Cloud API for Node.js and the browser
Installation |Development |Conventions |Docs |Examples |Building |Releasing |License
particle-api-js is available fromnpm to use in Node.js,bower or jsDelivr CDN for use in the browser.
$ npm install particle-api-js$ bower install particle-api-js<scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/particle-api-js@8/dist/particle.min.js"></script>
All essential commands are available at the root vianpm run <script name> - e.g.npm run lint. To view the available commands, run:npm run
How to run your tests
TheAgent integration tests (source) depend on a real HTTP api backend and a valid Particle access token. Be sure to set relevant environment variables to avoid test failures. You can prefix commands test commands like thisPARTICLE_API_BASE_URL=<url> PARTICLE_API_TOKEN=<token> npm test
npm test runs the tests.
npm run coverage shows code coverage
npm run test:browser runs tests in a browser viakarma.
npm run test:ci runs tests in the exact same way CI system does
How to write scripts that execute against local code changes?
Source code lives in the./src directory and is built for release via thenpm run build command. To create a simple script file to test your changes, follow these steps:
- create a
jsfile on your local machine:touch my-api-test.js(somewhere outside of the root of this repo) - within your test
jsfile, init the api client like so:
constParticleAPI=require('./path/to/particle-api-js');// Make sure to substitute to correct pathconstapi=newParticleAPI();
- add in any api calls, etc required to validate you changes
constdevices=awaitapi.listDevices({auth:'<particle-auth-token>'});console.log('MY DEVICES:',devices);
- run it:
node ./path/to/my-api-test.js
NOTE: Requiring the root directory works via themain field specified in Particle API JS'package.json file (docs)
How to name npm scripts
npm scripts are the primary means of executing programmatic tasks (e.g. tests, linting, releasing, etc) within the repo. to view available scripts, runnpm run.
when creating a new script, be sure it does not already exist and use the following naming convention:
<category>:[<subcategory>]:[<action>]
our standard categories include:test,lint,build,clean,docs,package,dependencies, andrelease. top-level scripts - e.g.npm run clean - will typically run all of its subcategories (e.g.npm run clean:dist && npm run clean:tmp).
npm itself includes special handling fortest andstart (doc:1,2) amongst otherlifecycle scripts - use these to expose key testing and start-up commands.
sometimes your new script will be very similar to an existing script. in those cases, try to extend the existing script before adding another one.
- npm scripts form thedeveloper's API for the repo and all of its packages - key orchestration commands should be exposed here
- document developer-facing process / tooling instructions in theDevelopment section
- plan to release your changes upon merging to
main- refrain from merging if you cannot so you don't leave unpublished changes to others - avoid making changes in files unrelated to the work you are doing so you aren't having to publish trivial updates
- test files live alongside their source files and are named like
*.test.jsor*.spec.js - if the linter does not flag your code (error or warning), it's formatted properly
- avoid reformatting unflagged code as it can obscure more meaningful changes and increase the chance of merge conflicts
- todo comments include your last name and are formatted like:
TODO (mirande): <message>
First, read thedocumentation for Particle API JS on the Documentation website. It contains examples to get started.
For more details, read theAPI reference on GitHub.
Thereare many snippets of using Particle API JS on the Documentation website and some complete examples in theGitHub examples directory.
Make your changes to the files in thesrc directory, then from the project directory run:
$ npm run buildThedist directory will contain the compiled and minified files that can be included in your project.
Run tests to make sure your changes are good:
$ npm testUpdate the API docs with your changes:
$ npm run docsSee the release process in theRELEASE.md file.
Copyright © 2016 Particle Industries, Inc. Released under the Apache 2.0 license. SeeLICENSE for details.
About
JS Library for the Particle API