Valence-url NPM

node-valence-url

Module for dealing with Valence API versions and calculating routes in a semver-esque fashion.

Usage

node-valence-url makes route calculation with Valence APIs easier. Define a ValenceRoute, then use the ValenceUrlResolver to resolve matching versions with your LMS. ValenceUrlResolver.resolve() returns promise-y things.

The ValenceUrlResolver does not have any built-in mechanism for updating its internally-stored versions; for this reason, it is recommended that you cache your ValenceUrlResolvers (one per tenant), and if the cached resolver is stale, a new one is created which will re-fetch the LMS' versions.

var valenceUrl = require('node-valence-url');
var ValenceRoute = valenceUrl.ValenceRoute;

var resolver = new ValenceUrlResolver('http://example.com', 'an auth token');

var route = new ValenceRoute.Simple('foo');
yield resolver.resolve(route); // http://example.com/foo

route = new ValenceRoute.Versioned('lp', 'foo', 'bar', '^1.5');
yield resolver.resolve(route); // http://example.com/foo/1.6/bar

route = new ValenceRoute.Versioned('lp', 'foo', 'bar', '^1.9');
yield resolver.resolve(route); // throws if LP does not support versions 1.9 and up on LMS

ValenceUrlResolver API

The ValenceUrlResolver class does route calculation based off of knowledge about what an LMS supports and information about the desired route (ValenceRoute).

`ValenceUrlResolver(Object options)`

Constructor. options must contain a string tenantUrl, which is the base URL of the LMS that this resolver is running against, and either a string authToken, or an Array versions. If versions is present, this will be used to resolve versions (prevents doing call to /d2l/api/versions/). If not present, then the authToken string is used along with the tenantUrl to kick off a request to fetch the LMS' versions information.

`ValenceUrlResolver.resolve(ValenceRoute route)`

Resolves a ValenceRoute object into a string route that has the highest matching version for the correct product filled in. Returns a Promise that resolves to the resolved route.

ValenceRoute API

ValenceRoute is a set of classes that represent a Valence URL route - including the product, prefix, suffix, and optionally a preferred SemVer range.

`ValenceRoute()`

Base class for other routes.

`ValenceRoute.Simple(String path)`

Constructor. Simple Valence route (without version), e.g. /d2l/api/versions/. Only has the path property, which just returns the string given to the constructor.

`ValenceRoute.Versioned(String product, String prefix, String suffix[, String desiredSemVer])`

Constructor. Versioned Valence route, e.g. /d2l/api/lp/1.5/enrollments/myenrollments/. Has the following properties:

product - should match a ProductCode that appears in a /d2l/api/versions/ call - e.g. "lp"
prefix - part before the version in the route - e.g. "/d2l/api/lp/"
suffix - part after the version in the route - e.g. "/enrollments/myenrollments/"
desiredSemVer - optional; when resolving a route, use this SemVer range to specify which version(s) we want to allow the route to be resolve with - e.g. "^1.4"

`ValenceRoute.LP(String suffix[, String desiredSemVer])`

Convenience constructor. Similar to Versioned, but sets product to lp and prefix to /d2l/api/lp/.

`ValenceRoute.LE(String suffix[, String desiredSemVer])`

Convenience constructor. Similar to Versioned, but sets product to le and prefix to /d2l/api/le/.

`unstable` Routes

node-valence-url supports using unstable API routes on ValenceRoute.Versioned, ValenceRoute.LP, and ValenceRoute.LE. Simply pass 'unstable' as your desiredSemVer when instantiating a route, and calling ValenceUrlResolver.resolve() on that Route will return the unstable route.

Contributing

Fork the repository. Committing directly against this repository is highly discouraged.
Make your modifications in a branch, updating and writing new tests as necessary in the test directory.
Ensure that all tests pass with npm test
rebase your changes against master. Do not merge.
Submit a pull request to this repository. Wait for tests to run and someone to chime in.