Quotable REST API client

This package is a TypeScript based wrapper around the public Quotable REST APIs

• Quotable REST API client
  • Gettting started
  • Installation
  • Usage
  • Quotable class
    • Constructor
    • Methods
    • getAuthors
    • getQuote
    • getQuotes
    • getRandomQuotes
    • getTags
  • Types
    • Author
    • AuthorRequest
    • AuthorResponse
    • ListQuoteRequest
    • ListQuoteResponse
    • Order
    • Quote
    • RandomQuoteRequest
    • RequestParams
    • Result
    • SortBy
    • Tag
    • TagRequest
  • Authors
  • Links

Prerequisites

This package requires NodeJS (version 18 or later) and a node package manager (Npm, Yarn, Pnpm or Bun).

To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
v10.1.0
v18.18.0

Gettting started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites.

Start with cloning this repo on your local machine:

$ git clone https://github.com/mariolazzari/quotable
$ cd quotable

To install and set up the library, run:

npm install @mariolazzari/quotable

Usage

Import package

import { Quotable } from "@mariolazzari/quotable"

Watch mode

npm test

Unit testing

npm test

Bulding new version

npm build

This task will create a distribution version of the project inside your local dist/ folder.

Quotable class

Quotable class content handles all the requests and the responses to Quotable REST APIs.

Constructor

In order to initialize Quotable client:

const quotable = new Quotable();

Methods

Quotable client includes the following methods:

getAuthors

Description

This asynchronous method handles GET /api/authors REST API.

Prototype

async getAuthors(params:AuthorRequest): Promise<Result<AuthorResponse>> 

Sample code

const sortBy: SortBy<Author> = 'quoteCount';
const order: Order = 'desc';
const { success, data, error } = await quotable.getAuthors({ 
    sortBy,
    order,
});

getQuote

Description

This asynchronous method handles GET /api/quotes/:id REST API.

Prototype

async getQuote(id:string): Promise<Result<Quote>> 

Sample code

const id = '2qpi1ZKL9Ko';
const { data, error, success } = await quotable.getQuote(id);

getQuotes

Description

This asynchronous method handles GET /api/quotes REST API.

Prototype

async getQuotes(params:ListQuoteRequest): Promise<Result<ListQuoteResponse>> 

Sample code

const tags = 'love | happiness';
const { data, error, success } = await quotable.getQuotes({ tags });

getRandomQuotes

Description

This asynchronous method handles GET /api/quotes/random REST API.

Prototype

async getQuotes(params:RandomQuoteRequest): Promise<Result<Quote[]>> 

Sample code

const tags = 'technology,famous-quotes';
const { success, data, error } = await quotable.getRandomQuotes({ tags });

getTags

Description

This asynchronous method handles GET /api/tags REST API.

Prototype

async getTags(params:TagRequest): Promise<Result<Tag[]>> 

Sample code

const sortBy: SortBy<Tag> = 'name';
const { success, data, error } = await quotable.getTags({ sortBy });

Types

Author

type Author = {
  // A unique id for this author
  _id: string;
  // A brief, one paragraph bio of the author. Source: wiki API
  bio: string;
  // A one-line description of the author. Typically it is the person's primary
  // occupation or what they are know for.
  description: string;
  // The link to the author's wikipedia page or official website
  link: string;
  // The authors full name
  name: string;
  // A slug is a URL-friendly ID derived from the authors name. It can be used as
  slug: string;
  // The number of quotes by this author
  quoteCount: string;
};

AuthorRequest

type AuthorRequest = Partial<{
  slug: string;
  sortBy: SortBy<Author>;
  order: Order;
  limit: number;
  page: number;
}>;

AuthorResponse

type AuthorResponse = {
  // The number of results included in this response.
  count: number;
  // The total number of results matching this request.
  totalCount: number;
  // The current page number
  page: number;
  // The total number of pages matching this request
  totalPages: number;
  // The 1-based index of the last result included in this response. This shows the
  // current pagination offset.
  lastItemIndex: number | null;
  // The array of authors
  results: Author[];
};

ListQuoteRequest

type ListQuoteRequest = RandomQuoteParams &
  Partial<{
    sortBy: Sort<Quote>;
    order: Order;
    page: number;
  }>;

ListQuoteResponse

type ListQuoteResponse = {
  // The number of quotes returned in this response
  count: number;
  // The total number of quotes matching this query
  totalCount: number;
  // The current page number
  page: number;
  // The total number of pages matching this request
  totalPages: number;
  // The 1-based index of the last result included in the current response.
  lastItemIndex: number;
  // The array of quotes
  results: Quote[];
};

Order

type Order = 'asc' | 'desc' | 'default';

Quote

type Quote = {
  _id: string;
  // The quotation text
  content: string;
  // The full name of the author
  author: string;
  // The `slug` of the quote author
  authorSlug: string;
  // The length of quote (number of characters)
  length: number;
  // An array of tag names for this quote
  tags: string[];
};

RandomQuoteRequest

type RandomQuoteRequest = Partial<{
  limit: number;
  maxLength: number;
  minLength: number;
  tags: string;
  author: string;
}>;

RequestParams

type RequestParams =
  | ListQuoteRequest
  | RandomQuoteRequest
  | AuthorRequest
  | TagRequest;

Result

Discriminated union containig api response.

type Result<T> =
  | {
      success: true;
      data: T;
    }
  | {
      success: false;
      error: string;
    };

SortBy

type Sort<T> = keyof T;

Tag

type Tag = {
  _id: string;
  name: string;
  dateAdded: string;
  dateModified: string;
  __v: number;
  quoteCount: number;
};

TagRequest

type TagRequest = Partial<{
  sortBy: SortBy<Tag>;
  order: Order;
}>;

Authors

• Mario Lazzari - Initial work

Links

• Demo app
• My personal site
• My github profile
• Quotable API documentation