This package is a JavaScript client of the Halo 5 Developer's API [Beta], written in TypeScript (a superset of JavaScript) and transpiled into a Node JS module.
It provides one function for each endpoint, returning a promise. There are some additional functions that offer alternate access to some endpoints.
Using this project with your development IDE, such as WebStorm, Visual Studio or Atom, it will provide both an API and static type checking for what can be a complex entanglement of statistics and metadata.
- One function per endpoint, with a handful of helper functions provided.
- Supports caching with redis.
- Built in retries when rate limited.
- Fully documented response typing.
- Available on NPM.
- Unit tested.
If you haven't already grabbed a key, head to developer.haloapi.com, sign in, head to Products and grab a key. The documentation for the API itself is also available there.
If you have any issues there are forums available here, and a thread for this particular binding here.
TypeScript is a language developed by Microsoft in order to add static typing to the JavaScript programming language. While this project is written with TypeScript, it produces JavaScript that is readable and usable without even knowing that TypeScript exists.
To find out more about TypeScript, head here.
- Halo Waypoint API Support Forum
- Halo Waypoint haloapi.js Thread
- haloapi.js NPM Package
- haloapi.js Continous Integration (Travis CI)
- haloapi.js Usage Documentation
- Official Halo API Documentation
- JSON Schemas for Halo API Responses
This project can be installed as a node module with
$ npm install haloapi
Easy!
If you don't have Node or NPM, go ahead and install it.
Requires Node version 0.11 or later.
Brief usage instructions follow. More in depth usage info is available here.
Usage with plain old JavaScript.
var HaloAPI = require('haloapi');
var h5 = new HaloAPI('YOUR API KEY');
(If you've cloned this repo use require('./js/index')
)
h5.metadata.weapons().then(function (weapons) {
weapons.forEach(function (weapon) {
console.log(weapon.name, '\n\t', weapon.description);
});
});
h5.profile.emblemImage("Your Gamertag").then(function (url) {
console.log(url);
});
With all requests, you are returned a Promise. Basic promise usage is as follows:
h5.stats.playerMatches("Frankie")
.then(function (data) {
// success, iterate through your matches
})
.catch(function (error) {
// uh oh, handle error here.
});
With ECMAScript2016 (ES7), you can do the following, which will await in a non-blocking manner:
let url = await h5.stats.spartanImage`Frankie`;
Using with TypeScript (completely optional)
/// <reference path="ts/haloapi.d.ts"/>
import HaloAPI = require('haloapi');
var h5: IHaloAPI = new HaloAPI('YOUR API KEY');
h5.metadata.weapons().then((weapons: Weapons) => {
weapons.forEach((weapon: Weapon) => {
console.log(weapon.name, '\n\t', weapon.description);
});
});
- Complete the TypeScript definitions for remaining stats endpoints.
If you've modified the TypeScript sources, you'll need to regenerate the JS. Run this in a terminal at the top-level directory for this repository.
$ npm run build
Documentation is currently being built with docco. All files in the examples/docs/
directory are converted to html files with docco and hosted at, e.g. https://azz.github.io/haloapi.js/docco/<filename>.html
. This is using GitHub pages feature (see branch gh-pages
). The npm run document
command will build these docs. If you are interested in sending a pull request with new docs, you may either send just the JS file and I can generate the docs, or follow these instructions carefully:
First time only:
$ mkdir -p docs && cd docs
$ git checkout --orphan gh-pages # Grab current docs
$ git branch -u origin/gh-pages # Track gh-pages branch on remote.
$ git branch -D master # We don't need code branches.
$ cd .. # Back to code repository root
And for each time you want to build/push documentation:
$ npm run document # Will generate files in docs/
$ cd docs # Important!
$ git add docco/*.html # Or just files you want to add
$ git commit -m "YOUR COMMIT MESSAGE"
$ git push origin gh-pages
$ cd .. # Return to code repo.
See this blog post for some explanation of what just happened.
Test suite is written with Mocha and Chai. Before running tests, set the HALOAPI_KEY
variable in your environment.
$ export HALOAPI_KEY=YOUR-API-KEY-HERE
And run all tests with:
$ npm test
All commits pushed to this repository are automatically tested on Travis CI.
Feel free to send a pull request if you wish to contribute.
API Client provided under the MIT license, see LICENSE.md
.
Halo 5: Guardians © Microsoft Corporation. haloapi.js was created under Microsoft's "[Game Content Usage Rules](Game Content Usage Rules)" using assets from Halo 5: Guardians, and it is not endorsed by or affiliated with Microsoft.
Contributors and users should also read the rules.