ollivander v2.0.2
🪄 Ollivander
Wonde API client for Node.js, browsers, and workers
- ⏳ Promise-based API. For all of that
async
/await
goodness! - 🏫 Multi-school support. Make one request for multiple schools!
- 📄 Automatic pagination aggregation. Wonde's paginated API responses are automatically aggregated into one!
- 💪 TypeScript. Fully typed and self-documenting!
🚀 Quick Start
Install
# npm
npm i ollivander
# or yarn
yarn add ollivander
Import
// ESM / TypeScript
import { $wonde } from "ollivander";
// or CommonJS
const { $wonde } = require("ollivander");
Example Usage
Fetch all students for two schools:
const schools = await $wonde((school) => `/schools/${school}/students`, {
schools: ["A123456789", "A987654321"],
token: "abc123",
});
console.log(schools["A123456789"]);
// => Array of school A123456789's students
🏫 Single versus multi-school
Single school mode
const students = await $wonde("/schools/A123456789/students", {
token: "abc123",
});
console.log(students);
// => Array of school A123456789's students
// => i.e. [ ... ]
Multi-school mode
const schools = await $wonde((school) => `/schools/${school}/students`, {
schools: ["A123456789", "A987654321"],
token: "abc123",
});
console.log(schools);
// => Object mapping schools to their array of students
// => i.e. { 'A123456789': [ ... ], 'A987654321': [ ... ] }
💪 TypeScript Support
Wonde responses can be type assisted using generics:
type Student = { ... };
const students = await $wonde<Student>("/schools/A123456789/students", {
token: "abc123",
});
// => Students now has type definitions
♻ Auto Retry
Ollivander can be configured to retry requests if an error is encountered:
const students = await $wonde("/schools/A123456789/students", {
token: "abc123",
retry: 5, // => Request will retry 5 times before giving up
});
By default, requests will retry
1
time (except forPOST
,PUT
, andPATCH
requests, which will not retry).
📂 HTTP Headers
You can supply additional HTTP headers to Wonde's API:
const students = await $wonde("/schools/A123456789/students", {
token: "abc123",
headers: {
some: "header", // => This will be included in the request (including every paginated request)
},
});
⛓ Includes
You can instruct Wonde's API to populate relationships with includes. Typically, this would be done with the includes
search parameter, but Ollivander has a specific option for includes:
const students = await $wonde("/schools/A123456789/students", {
token: "abc123",
includes: ["classes"], // => Each student object will include their respective classes
});
🔢 Per Page
Wonde's API returns paginated responses for arrays of data. You can increase the number of resources returned per request (reducing the overall number of requests):
const students = await $wonde("/schools/A123456789/students", {
token: "abc123",
perPage: 200, // => Wonde's API caps this value at 200 (5000 when retrieving attendance sessions)
});
⚠ It's important to remember that Ollivander will handle paginated responses from Wonde so you never need to make more than one request.
However, increasing the
perPage
option will still reduce Ollivander's request time because of the overhead encountered when making a request to Wonde's API.
🌍 Wonde Endpoints
Wonde's API has separate endpoints/base URLs for the UK and Australia/New Zealand. You can find these endpoints on Wonde's API Reference, or import them as constants from Ollivander:
// ESM / TypeScript
import {
UK,
REST_OF_THE_WORLD,
AUSTRALIA,
NEW_ZEALAND,
} from "ollivander/endpoints";
// or CommonJS
const {
UK,
REST_OF_THE_WORLD,
AUSTRALIA,
NEW_ZEALAND,
} = require("ollivander/endpoints");
const students = await $wonde("/schools/A123456789/students", {
baseURL: AUSTRALIA,
});
By default, Ollivander will use Wonde's endpoint for the UK/Rest of the World.
⚖ License
Ollivander is licensed under the MIT License
.