Philosophy API client

This TypeScript based package implements a REST API client to the wonderfull Philosophy API free project.

• Philosophy API client
  • Installation
  • Usage
  • Philosophy class
    • Constructor
    • Methods
      • getBooks
      • getBook
      • getIdeas
      • getIdea
      • getPhilosophers
      • getPhilosopher
      • getRoot
      • getSchools
      • getSchool
  • Types
    • Book
    • Idea
    • Philosopher
    • Request
    • Response
    • Result
    • Root
    • School
  • 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

Installation

BEFORE YOU INSTALL: please read the prerequisites.

Start with cloning this repo on your local machine:

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

To install and set up the library, run:

npm install @mariolazzari/rijks

Usage

Import package

import { Philosophy } from "@mariolazzari/philosophy-api"

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

Philosophy class

Philosophy class handles all the requests and the responses to the Philosophy API project.

Constructor

In order to initialize Philosophy client:

const client = new Philosophy()

No parameters are required by this contrsuctor.

Methods

Philosophy client includes the following public methods:

getBooks

Description

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

Prototype

async getBooks(search: string, page: number): Promise<Result<Book[]>>

Sample code

const params: Request = {search: "title"}
const books: Response<Books[]> = await client.getBooks(params)

getBook

Description

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

Prototype

async getBooks(id: number): Promise<Result<Book>>

Sample code

const id:number = 123;
const book: Response<Book> = await client.getBooks(id)

getIdeas

Description

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

Prototype

async getBooks(search: string, page: number): Promise<Result<Idea[]>>

Sample code

const params: Request = {search: "god"}
const ideas: Response<Idea[]> = await client.getBooks(params)

getIdea

Description

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

Prototype

async getBooks(id: number): Promise<Result<Idea>>

Sample code

const id:number = 123;
const idea: Response<Idea> = await client.getBooks(id)

getPhilosophers

Description

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

Prototype

async getBooks(search: string, page: number): Promise<Result<Philosopher[]>>

Sample code

const params: Request = {search: "Kant"}
const philos: Response<Philosopher[]> = await client.getPhilosophers(params)

getPhilosopher

Description

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

Prototype

async getPhilosopher(id: number): Promise<Result<Philosopher>>

Sample code

const id:number = 123;
const philo: Response<Philosopher> = await client.getPhilosopher(id)

getRoot

Description

This asynchronous method handles GET /api/ REST API.

Prototype

async getRoot(): Promise<Result<Root>>

Sample code

const root: Response<Root> = await client.getRoot()

getSchools

Description

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

Prototype

async getSchools(search: string, page: number): Promise<Result<School[]>>

Sample code

const params: Request = {search: "Idealism"}
const schools: Response<School[]> = await client.getSchools(params)

getSchool

Description

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

Prototype

async getSchool(id: number): Promise<Result<School>>

Sample code

const id:number = 123;
const school: Response<School> = await client.getSchool(id)

Types

In order to implement all features, the following common types have been implemended:

Book

type Book = {
  id: number;
  title: string;
  cover: string;
  abstract: string;
  country: string;
  language: string;
  published: string;
  date: Date;
  author: string;
};

Idea

type Idea = {
  id: number;
  author: string;
  quote: string;
};

Philosopher

type Philosopher = {
  id: number;
  name: string;
  photo: string;
  born_date: string;
  born: Date;
  death_date: string;
  dead: Date;
  nationality: string;
  era: string;
  school: string[];
  schools: string[];
  ideas: string[];
  books: string[];
};

Request

type Request = Partial<{
  url: string;
  search: string;
  page: number;
}>;

Response

type Response<T> = Partial<{
  data: Result<T>;
  error: string;
}>;

Result

type Result<T> = {
  count: number;
  previous: string;
  next: string;
  results: T;
};

Root

type Root = {
  philosophers: string;
  ideas: string;
  books: string;
  schools: string;
};

School

type School = {
  id: number;
  name: string;
  philosophers: string[];
};

Authors

• Mario Lazzari - Initial work

Links

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