Skip to content

caetanojpo/gutenberg-api

BranchesTags

Repository files navigation

Project Gutenberg Text Analysis API

Node.js TypeScript Express Mongoose

A REST API for analyzing Project Gutenberg e-books with LLM-powered text analysis, built with Node.js and Clean Architecture.

📦 Tech Stack

  • Runtime: Node.js

  • Framework: Express

  • Database: MongoDB (Mongoose ODM)

  • Language: TypeScript

  • Testing: Jest

  • Logging: Winston

  • Deployment: Render

  • LLM Integration: [Groq]

  • Architecture: Clean Architecture

⚙️ Installation & Running

Clone the repository:

git clone [https://github.com/yourusername/project-gutenberg-api.git](https://github.com/yourusername/project-gutenberg-api.git)

Access folder:

cd project-gutenberg-api

Install dependencies:

npm install

Docker:

If you wish you can use the docker-composer file that is already set in the project

docker-compose up -d

❗ You will need to configure the DB connection string on .env file

Run the application:

npm run dev

🔧 Configuration

Create a .env file using the .env.example template. Replace placeholders with actual values:

PORT=8000
NODE_ENV=dev
LOG_LEVEL=info

# Database settings
DB_URI=
DB_USER=
DB_PASS=

# CORS allowed origins
ALLOWED_ORIGINS=*

#URLS
GUTENBERG_BASE_URL=https://www.gutenberg.org
DEV_API_URL=http://localhost:8000
PROD_API_URL=

#AUTH
JWT_SECRET=

GROQ_KEY=

📚 API Endpoints

0. Swagger Link

https://gutenberg-api-uwq7.onrender.com/api-docs

0.1 Postman Collection

Download it here

1. Auth

Base URL

https://gutenberg-api-uwq7.onrender.com/auth

POST /auth/login - ❌ No Authentication

Request Example

{
  "email": "user@example.com",
  "password": "yourPassword123"
}

Response Examples

  • Success Response

    Status Code: 201 Created

{
  "success": true,
  "message": "User authenticated successfully",
  "data": "JWT_TOKEN",
  "statusCode": 201
}

2. Users

Base URL

https://gutenberg-api-uwq7.onrender.com/users

POST /users - ❌ No Authentication

Request Example

{
  "username": "JohnDoe",
  "email": "johndoe@example.com",
  "password": "securePassword123"
}

Response Examples

  • Success Response

    Status Code: 201 Created

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": "user_id",
    "token": "JWT_TOKEN"
  },
  "statusCode": 201
}

GET /users/:id - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 200 OK

{
  "success": true,
  "message": "User found",
  "data": {
    "id": "user_id",
    "username": "JohnDoe",
    "email": "johndoe@example.com",
    "isActive": true
  },
  "statusCode": 200
}

GET /users/email/:email - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 200 OK

{
  "success": true,
  "message": "User found",
  "data": {
    "id": "user_id",
    "username": "JohnDoe",
    "email": "johndoe@example.com",
    "isActive": true
  },
  "statusCode": 200
}

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

PUT /users/:id - ✅ Requires Authentication

Request Example

{
  "username": "JohnDoeUpdated",
  "email": "johnupdated@example.com",
  "password": "newSecurePass123"
}

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

DELETE /users/soft/:id (Soft Delete) - ✅ Requires Authentication

Response Examples

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

DELETE /users/hard/:id (Hard Delete) - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

2. Books

Base URL

https://gutenberg-api-uwq7.onrender.com/books

POST /books - ✅ Requires Authentication

Request Example

{
  "gutenbergId": "12345",
  "title": "Pride and Prejudice",
  "author": "Jane Austen",
  "coverPictureUrl": "https://example.com/cover.jpg",
  "metadata": {
    "published": "1813",
    "downloads": 50000,
    "language": "English",
    "category": "Fiction",
    "rights": "Public Domain"
  },
  "content": "Full book content here..."
}

Response Examples

  • Success Response

    Status Code: 201 Created

{
  "success": true,
  "message": "Book created successfully",
  "data": "65a3bde50fbb9c4a1d23f0d9",
  "statusCode": 201
}

GET /books/:id - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 200 OK

{
  "message": "Book found",
  "data": {
    "id": "65a3bde50fbb9c4a1d23f0d9",
    "gutenbergId": "12345",
    "title": "Pride and Prejudice",
    "author": "Jane Austen",
    "coverPictureUrl": "https://example.com/cover.jpg",
    "metadata": {
      "published": "1813",
      "downloads": 50000,
      "language": "English",
      "category": "Fiction",
      "rights": "Public Domain"
    },
    "content": "Full book content here..."
  }
}

GET /books/gutenberg/:gutenbergId - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 200 OK

{
  "success": true,
  "message": "User found",
  "data": {
    "id": "user_id",
    "username": "JohnDoe",
    "email": "johndoe@example.com",
    "isActive": true
  },
  "statusCode": 200
}

GET /books - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 200 OK

{
  "message": "Books found",
  "data": [
    {
      "id": "65a3bde50fbb9c4a1d23f0d9",
      "gutenbergId": "12345",
      "title": "Pride and Prejudice",
      "author": "Jane Austen",
      "coverPictureUrl": "https://example.com/cover.jpg",
      "metadata": {
        "published": "1813",
        "downloads": 50000,
        "language": "English",
        "category": "Fiction",
        "rights": "Public Domain"
      }
    }
  ]
}

GET /books/author/:author - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 200 OK

{
  "message": "Books found",
  "data": [
    {
      "id": "65a3bde50fbb9c4a1d23f0d9",
      "gutenbergId": "12345",
      "title": "Pride and Prejudice",
      "author": "Jane Austen",
      "coverPictureUrl": "https://example.com/cover.jpg",
      "metadata": {
        "published": "1813",
        "downloads": 50000,
        "language": "English",
        "category": "Fiction",
        "rights": "Public Domain"
      }
    }
  ]
}

PATCH /books/content/:id - ✅ Requires Authentication

Request Example

{
  "content": "Updated book content..."
}

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

PATCH /books/metadata/:id - ✅ Requires Authentication

Request Example

{
  "metadata": {
    "published": "1813",
    "downloads": 55000,
    "language": "English",
    "category": "Fiction",
    "rights": "Public Domain"
  }
}

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

DELETE /users/soft/:id (Soft Delete) - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

DELETE /books/:id - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 204 No Content

{
  "success": true,
  "message": "",
  "data": null,
  "statusCode": 204
}

3. Gutenberg

Base URL

https://gutenberg-api-uwq7.onrender.com/gutenberg

POST /gutenberg/:gutenbergId - ✅ Requires Authentication

Response Examples

  • Success Response

    Status Code: 201 Created

{
  "success": true,
  "message": "Book saved successfully",
  "data": "65a3bde50fbb9c4a1d23f0d9"
  "statusCode": 201
}

4. LLM

Base URL

https://gutenberg-api-uwq7.onrender.com/llm

POST /llm - ✅ Requires Authentication

Request Example

{
  "id": "1342",
  "action": "SUMMARY"
}

Response Examples

  • Success Response

    Status Code: 200 Ok

{
  "success": true,
  "message": "Groq response received",
  "data": "This book is a classic novel that explores themes of love and social status..."
  "statusCode": 201
}

🚀 Deployment

Deployed on Render with MongoDB Atlas. Environment variables configured via Render dashboard:

# Server settings
PORT=8000
NODE_ENV=dev
LOG_LEVEL=info

# Database settings
DB_URI=
DB_USER=
DB_PASS=

# CORS allowed origins
ALLOWED_ORIGINS=*

#URLS
GUTENBERG_BASE_URL=https://www.gutenberg.org
DEV_API_URL=http://localhost:8000
PROD_API_URL=

#AUTH
JWT_SECRET=

GROQ_KEY=

🧪 Testing

Run unit tests with Jest:

npm test

📹 Loom Walkthrough

Watch the video)

📒 Architecture Notes:

  • Clean architecture layers:

    • application/: Business logic

    • domain/: Entities and interfaces

    • infrastructure/: Database/LLM integrations

    • adapter/: Express routes

  • Migrated MongoDB from local Docker to Atlas for scalability

  • Winston logger with production-grade configurations

  • JWT authentication for secure endpoints

About

Book API integration with Project Gutenberg's archive and AI (Groq) - TypeScript - REST API

gutenberg-api-uwq7.onrender.com/api-docs

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages