'The Lord of the Rings' API SDK

Introduction

A TypeScript SDK for 'The Lord of the Rings' API.

Installation

$ yarn add @derekburrows/lotr-api-sdk

Usage

Initialization

The SDK requires the below parameters for initialization:

• <URL> : a URL for the 'The Lord of the Rings' API
• <KEY> : an access token for authentication

Note: Please see 'The Lord of the Rings' API to obtain these.

import LotrApiSdk from 'lotr-api-sdk';

const sdk = new LotrApiSdk({
  url: '<URL>',
  key: '<KEY>',
});

Options

The SDK supports filtering, pagination, and sorting across all methods via the Options interface.

Interface

interface Options {
  filters?: Filters;
  page?: Page;
  sort?: Sort;
}

Example

import Options, { SortOrder } from '@derekburrows/lotr-api-sdk/options';

import {
  ExistsFilter,
  IncludesFilter,
  MatchesFilter,
  RegExpFilter,
  RelationalFilter,
  RelationalOperator,
} from '@derekburrows/lotr-api-sdk/filters';

const options: Options = {
  filters: [
    new ExistsFilter('key', false),
    new IncludesFilter('key', ['value1', 'value2'], false),
    new MatchesFilter('key', 'value', false),
    new RegExpFilter('key', new RegExp('value'), false),
    new RelationalFilter('key', 0, RelationalOperator.LessThan),
  ],
  page: {
    limit: 1,
    offset: 1,
    page: 1,
  },
  sort: {
    key: 'key',
    order: SortOrder.Ascending,
  },
};

Filters

type Filters = Array<Filter>;

Exists

Records where key exists or doesn't exist.

new ExistsFilter(key: string, negate: boolean = false)

Includes

Records where key is included or not included in the value array.

new IncludesFilter(key: string, value: Array<string>, negate: boolean = false)

Matches

Records where key matches or doesn't match the value string.

new MatchesFilter(key: string, value: string, negate: boolean = false)

Regular Expression

Records where key matches or doesn't match the value regular expression.

new RegExpFilter(key: string, value: string, negate: boolean = false)

Relational

Records where key is 'less than', 'greater than', or 'greater than or equal to' the value number.

enum RelationalOperator {
  LessThan = '<',
  GreaterThan = '>',
  GreaterThanOrEqualTo = '>=',
}

new RelationalFilter(key: string, value: number, operator: RelationalOperator)

Pagination

interface Page = {
  limit?: number;
  page?: number;
  offset?: number;
};

Sorting

enum SortOrder {
  Ascending = 'asc',
  Descending = 'desc',
}

interface Sort = {
  key: string;
  order: SortOrder;
};

Methods

The SDK exposes methods corresponding to the routes provided by the 'The Lord of the Rings' API.

Get All Movies

Gets all movies. (Unpaginated)

getAllMovies() : Promise<Movies>

Get Movies

Gets movies. (Paginated)

getMovies(options: Options) : Promise<MoviesResponse>

Get Movie

Gets the movie with the specified id.

getMovie(id: string, options: Options) : Promise<MoviesResponse>

Get All Movie Quotes

Gets all quotes from the movie with the specified id. (Unpaginated)

getAllMovieQuotes(id: string) : Promise<Quotes>

Get Movie Quotes

Gets quotes from the movie with the specified id. (Paginated)

getMovieQuotes(id: string, options: Options) : Promise<QuotesResponse>

Get All Quotes

Gets all quotes. (Unpaginated)

getAllQuotes() : Promise<Quotes>

Get Quotes

Gets quotes. (Paginated)

getQuotes(options: Options) : Promise<QuotesResponse>

Get Quote

Gets the quote with the specified id.

getQuote(id: string, options: Options): Promise<QuotesResponse>

Responses

Pagination

interface Pagination {
  total: number;
  limit: number;
  offset: number;
  page: number;
  pages: number;
}

Response

interface Response<T> extends Pagination {
  docs: Array<T>;
}

Movies Response

interface Movie {
  _id: string;
  name: string;
  runtimeInMinutes: number;
  budgetInMillions: number;
  boxOfficeRevenueInMillions: number;
  academyAwardNominations: number;
  academyAwardWins: number;
  rottenTomatoesScore: number;
}

type Movies = Array<Movie>;

interface MoviesResponse extends Response<Movie> {}

Quotes Response

interface Quote {
  _id: string;
  id: string;
  character: string;
  dialog: string;
  movie: string;
}

type Quotes = Array<Quote>;

interface QuotesResponse extends Response<Quote> {}

Local Development

Install Dependencies

To install dependencies:

$ yarn install

Build

To build the SDK:

$ yarn build

Test

To execute the test suite:

$ yarn test

Driver

The project includes a driver script which demonstrates initialization and invokation of the SDK.

The driver requires a .env file to be present at the project root in the following format:

URL='<URL>'
KEY='<KEY>'

To execute the driver (after installing dependencies):

$ yarn driver <method> <id>

Example:

$ yarn driver getMovie 5cd95395de30eff6ebccde56