The Lord of the Rings SDK
A library that wraps the The One API to Rule Them All, for all data regarding The Lord of the Rings series of novels by J. R. R. Tolkien and the official movie adaptation by Peter Jackson.
Installation and Setup
- NPM:
npm install @sherwinski/lotr-sdk - Yarn:
yarn add @sherwinski/lotr-sdk
Prior to using this library, users should create an account to generate an API token.
Usage
This library may be loaded as either a CommonJS or ES module:
import { LOTR } from '@sherwinski/lotr-sdk';
// or
const { LOTR } = require('@sherwinski/lotr-sdk');The LOTR class comes with several methods that allow users to query the
various endpoints of the Lord of the Rings API:
-
movies(): returns a list of all movies, including the "The Lord of the Rings" and the "The Hobbit" trilogies. Passing in an optional{ movieId }parameter returns one specific movie. -
movieQuotes({ movieId }): returns all movie quotes for one specific movie (only working for the LotR trilogy). -
quotes({ apiKey }): returns a list of all movie quotes. Passing in an optional{ quotesId }returns one specific movie quote. -
characters(): returns a list of characters including metadata like name, gender, realm, race and more.
These methods can be chained together with any number of modifiers for
pagination, sorting, and/or filtering. To finally retrieve the result from any
function, use the summon() function.
Please note that as each of these methods returns a
Promise,
they must be preceded by the
await
operator or chained with the
then()
Promise method.
Finally, users should note that the API that this library wraps includes a ratelimit of 100 requests per 10 minutes.
Example
// as an ES module
import { LOTR } from '@sherwinski/lotr-sdk';
const sdk = new LOTR({ apiKey: 'abc123' });
const quotes = await sdk.getAllQuotes().summon();
console.log(quotes);
/*
[
{
_id: '5cd96e05de30eff6ebcce7e9',
dialog: 'Deagol!',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfe9e',
id: '5cd96e05de30eff6ebcce7e9'
},
{
_id: '5cd96e05de30eff6ebcce84c',
dialog: "I didn't think it would end this way.",
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfe2e',
id: '5cd96e05de30eff6ebcce84c'
},
...
]
*/Alternatively:
// as a CJS module
const { LOTR } = require('@sherwinski/lotr-sdk');
LOTR({ apiKey: 'abc123' })
.quotes({ quoteId: '100' })
.summon()
.then((res) => console.log(res));Pagination
Fine-tune the number of responses returned by utilizing one or more of the following methods:
withPage(pageNumber)withPageSize(pageSizeNumber)withPageOffset(pageOffsetNumber)
const sdk = new LOTR({ apiKey: 'abc123' });
const quotes = quotes().withPage(1).withPageSize(5).withPageOffset(3).summon();
console.log(quotes);
/*
[
{
_id: '5cd96e05de30eff6ebcce7ec',
dialog: 'Give us that! Deagol my love',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfe9e',
id: '5cd96e05de30eff6ebcce7ec'
},
{
_id: '5cd96e05de30eff6ebcce7ed',
dialog: 'Why?',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfca7',
id: '5cd96e05de30eff6ebcce7ed'
},
{
_id: '5cd96e05de30eff6ebcce7ee',
dialog: "Because', it's my birthday and I wants it.",
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfe9e',
id: '5cd96e05de30eff6ebcce7ee'
},
{
_id: '5cd96e05de30eff6ebcce7ef',
dialog: 'Arrghh!',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfca7',
id: '5cd96e05de30eff6ebcce7ef'
},
{
_id: '5cd96e05de30eff6ebcce7f0',
dialog: 'They cursed us!',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfe9e',
id: '5cd96e05de30eff6ebcce7f0'
}
]
*/Sorting
Order responses by specifying any property found on the returning object and
optionally specify if the ordering should be asc or desc:
withSort(fieldString)withSortOrder(sortOrderString)
const sdk = new LOTR({ apiKey: 'abc123' });
const quotes = await quotes()
.withSort('character')
.withSortOrder('asc')
.withPageSize(5)
.summon();
console.log(quotes);
/*
[
{
_id: '5cd96e05de30eff6ebcce80e',
dialog: 'Hannon le.',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfbe6',
id: '5cd96e05de30eff6ebcce80e'
},
{
_id: '5cd96e05de30eff6ebcce80d',
dialog: "Et E'rello Endorenna ut'lien. Sinome maruvan ar Hildinyar tenn' Ambar-metta!",
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfbe6',
id: '5cd96e05de30eff6ebcce80d'
},
{
_id: '5cd96e05de30eff6ebcce830',
dialog: 'Show yourself.',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfbe6',
id: '5cd96e05de30eff6ebcce830'
},
{
_id: '5cd96e05de30eff6ebcce80f',
dialog: 'My friends, you bow to no-one.',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfbe6',
id: '5cd96e05de30eff6ebcce80f'
},
{
_id: '5cd96e05de30eff6ebcce80c',
dialog: 'This day does not belong to one man, but to all. Let us together rebuild this world, that we may share in the days of peace.',
movie: '5cd95395de30eff6ebccde5d',
character: '5cd99d4bde30eff6ebccfbe6',
id: '5cd96e05de30eff6ebcce80c'
}
]
*/Filtering
Refine response data by using parameter expressions which can be applied to any available key on the data models. For more examples, see the API documentation.
const sdk = new LOTR({ apiKey });
const quotes = await sdk
.quotes()
.withFilter({ dialog: 'You shall not pass!' })
.summon();
console.log(quotes);
/*
[
{
_id: '5cd96e05de30eff6ebccec8a',
dialog: 'You shall not pass!',
movie: '5cd95395de30eff6ebccde5b',
character: '5cd99d4bde30eff6ebccfea0',
id: '5cd96e05de30eff6ebccec8a'
}
]
*/Testing
To run this project's tests: clone the project, install dependencies and then run the test script:
git clone git@github.com:sherwinski/Sherwin-SDK.git
npm install
npm run test