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 [email protected]:sherwinski/Sherwin-SDK.git
npm install
npm run test