Bilichenko-aleksandr-sdk NPM

Lord Of The Rings SDK

HeaderImage

This SDK has been created for a purpose of making a bridge between Lord Of The Rings API. To save developers time for creation serialization layers and mixing different queries. With this SDK you are able to have a complete access to API and even more. Simple to install and easy to use.

Requirements

For being able to use all the functionality, that SDK provides, you will need to register at the API WebSite. After success registration you will receive an API key. It has to be used in an imported function call. The complete installation instructions is right below.

Note: this package will not work in not Node environment, as it includes core Node JS modules

Installation

All you need to make an SDK installed is just run the following script in your command line:

npm i bilichenko-aleksandr-sdk

SDK Initialization

As was mentioned before at this step you will need to have API key retrieved from API (How to retrieve an API key).

You have to import SDK to your application and provide following arguments to it:

apiKey (key that was retrieved from API)
options (optional parameter to set cache and logger)

Options argument is not a requirement, so you can skip it at all. But it might be helpful for debugging, or caching recurring queries. It has two properties

cacheTime: Number (time in milliseconds to reset cache)
loggerEnabled: Boolean (initialize an SDK with logger)

CommonJS

Common JS SDK initialization example with setting cache reset to 10 seconds and enabling logger:

const { LordOfTheRingsSdk } = require('bilichenko-aleksandr-sdk');

const sdk = LordOfTheRingsSdk('12345ApiKey', { cacheTime: 10000, loggerEnabled: true });

ES Modules

ES Modules SDK initialization example without enabling it features:

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk('12345ApiKey');

TypeScript

TypeScript example. Nest.js version of initializing SDK inside a controller, with a partial options enabled:

import { LordOfTheRingsSdk, ICharacterWithQuotesResponse } from 'bilichenko-aleksandr-sdk';

@Get()
    async getCharacterQuotes(): Promise<ICharacterWithQuotesResponse | null> {
        const sdk = LordOfTheRingsSdk(<apiKey>, {
            cacheTime: 1000,
        });

        const result = await sdk.characters.getQuotesOfCharacter(<id>));
        return result;
    }

Note: Nest.js is just an example. You can use same approach with any other TypeScript framework

Before use

Note: API has a limitation for requests. So you are able to send only 100 requests each 10 minutes.

We are highly recommending to enable cache with this time, to avoid any durability issues. Note that you will need to initialize SDK at the top level, to use the same scope for all users and share cached responses between them.

But this option is still on your choice.

SDK methods

SDK is created to make developers life easier. However it is just a layer between developers and API.

Our development team is working to cover as much usage cases as possible. But at the same moment we have left you some freedom in actions.

Please, discover the methods, that SDK provides, to understand how it can be useful for you.

Methods

Initialized SDK includes five blocks of functions to operate with specific entities.

books;
chapters;
characters;
movies;
quotes;

Note: params is always an optional parameter, you don't need to provide it if there is no pagination / sort / filter purpose for it

Books

getBookList(params);
searchBooksByName(name, params);
getBookTitles();
getBook(id);
getBookWithChapters(id, params);
getBookWithChaptersTitles(id);

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
const params = { limit: 2 };
sdk.books.getBookList(params)
    .then((result) => console.log(result));

Chapters

getAllChapters(params);
searchChaptersByName(name, params);
getAllBooksWithChapters();
getChapter(id);

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
sdk.chapters.searchChaptersByName('on')
    .then((result) => console.log(result));

Characters

getAllCharacters(params);
searchCharactersByName(name, params);
getRacesList();
getFemaleCharacters(params);
getMaleCharacters(params);
searchCharactersByRace(race, params);
getCharacter(id);
getQuotesOfCharacter(id, params);

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
const params = { limit: 2 };
sdk.characters.searchCharactersByRace('human', params)
    .then((result) => console.log(result));

Movies

getAllMovies(params);
searchMovieByName(name, params);
getMovie(id);
getQuotesOfMovie(id, params);

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
sdk.movies.getAllMovies()
    .then((result) => console.log(result));

Quotes

getAllQuotes(params);
getQuote(id);
getRandomQuote();

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
sdk.quotes.getRandomQuote()
    .then((result) => console.log(result));

Params object

Object called params is an optional object and might consist following properties:

limit?: number;
offset?: number;
page?: number;
sort?: Record<string, string | number>;
filter?: Record<string, string>

Note: we are not recommending to use sort and filter without a specific need. Some endpoints at the API side are not supporting this options. We are working to bring sort and filter to SDK layer for all possible cases. You will be able to have them in further releases.

Recommendations

Use offset and page properties separately. It's about a pagination concept, choose one to proceed with.
You can use sort property to apply sorting. Not every endpoint supports it, so make sure you are tested such use case in advance. You have to provide an object to sort, which will have a field name as a key and sorting direction as a value (1, -1, 'desc', 'asc').
You can use filter property to apply filtering. Not every endpoint supports it, so make sure you are tested such use case in advance. You have to provide an object to filter, which will have a field name as a key and filtering action string as a value.

Sorting example:

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
const params = { sort: { name: 'desc' } };
sdk.movies.getAllMovies(params)
    .then((result) => console.log(result));

Filtering example:

import { LordOfTheRingsSdk } from 'bilichenko-aleksandr-sdk';

const sdk = LordOfTheRingsSdk(apiKey);
const params = { filter: { name: '=Gandalf' } };
sdk.movies.getAllMovies(params)
    .then((result) => console.log(result));

Filtering options:

Use your value for filtering instead value and regular expression instead regex

match - =value
not match - !=value
include - =value1,value2
exclude - !=value1,value2
less than - <value
greater than - >value
regex - =regex

Error handling

For making a usage of current SDK more slight and safe we are not returning or throwing any errors from inside of it. In the success scenario you will always have a response. Consider that null is a response of failure. To understand a reason of it, please initialize SDK with logger enabled.

Development

Testing

Testing is available for development purpose, you may discover test cases in our GitHub Repository

It's developed with a help of Jest testing framework on a unit, integration and acceptance levels.

For this you will need to install development dependencies first:

npm i

Unit tests To run unit tests, execute following script:

npm run test:unit

Integration tests To run integration tests, execute following script:

npm run test:integration

Acceptance tests Before running acceptance tests, make sure you have provided an apiKey in tests/libs/testConfig.js file. To run them, execute following script:

npm run test:e2e

Design

If you are curious about architecture of current SDK, please discover our design.md to understand it better.

Contacts

If you have any purposes or troubles with current SDK - please open an issue in our GitHub Repository.

Our team will take it to work right after.

Happy Hacking!

sdk lord-of-the-rings

@everything-registry/sub-chunk-1234 @infinitebrahmanuniverse/nolb-bil @zalastax/nolb-bil

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago