API Documentation

Introduction

Welcome to the Nspxt Literary Excerpts API. This API provides random book excerpts from Project Gutenberg, the largest collection of free electronic books available online. All excerpts are up to 500 characters in length and include metadata about the original source.

Project Gutenberg offers over 60,000 free ebooks in various formats, focusing on older works for which U.S. copyright has expired. This API makes it easy to access random excerpts from these classic works for various applications.

Getting Started

The base URL for all API endpoints is:

https://[your-domain]/api

Admin Authentication Required

This section is only visible to authenticated administrators.

Login

API Endpoints

The following endpoints are available for retrieving book excerpts and related information:

Random Excerpt

GET /api/random-excerpt

Returns a random excerpt of up to 500 characters from a book in the Project Gutenberg collection.

Query Parameters:
Parameter Type Description
author string Filter by author name (partial match)
genre string Filter by genre (partial match)
year_from number Filter by publication year (minimum)
year_to number Filter by publication year (maximum)
Example Request:
curl -X GET "https://[your-domain]/api/random-excerpt?author=Dickens&year_from=1850"
Example Response:
{
  "excerpt": "It was the best of times, it was the worst of times, it was the age of wisdom...",
  "metadata": {
    "book_id": 98,
    "title": "A Tale of Two Cities",
    "author": "Charles Dickens",
    "publication_year": 1859,
    "language": "eng",
    "genres": ["Historical Fiction", "French Revolution"]
  },
  "attribution": "Excerpt from A Tale of Two Cities by Charles Dickens, provided by Nspxt",
  "gutenberg_url": "https://www.gutenberg.org/ebooks/98"
}

Books

GET /api/books

Returns a paginated list of books available in the database with their metadata.

Query Parameters:
Parameter Type Description
page number Page number (default: 1)
per_page number Results per page (default: 10, max: 50)
author string Filter by author name (partial match)
genre string Filter by genre (partial match)
q string Search term for title, author, or genre
Example Request:
curl -X GET "https://[your-domain]/api/books?page=1&per_page=5&q=Shakespeare"
Example Response:
{
  "books": [
    {
      "gutenberg_id": 1041,
      "title": "Hamlet",
      "author": "William Shakespeare",
      "publication_year": 1603,
      "language": "eng",
      "genres": ["Tragedy", "Drama"],
      "excerpt_count": 42
    },
    {
      "gutenberg_id": 1533,
      "title": "Macbeth",
      "author": "William Shakespeare",
      "publication_year": 1623,
      "language": "eng",
      "genres": ["Tragedy", "Drama"],
      "excerpt_count": 38
    }
  ],
  "pagination": {
    "total_books": 37,
    "page": 1,
    "per_page": 5,
    "total_pages": 8
  }
}

Genres

GET /api/genres

Returns a list of all genres available in the database with book counts.

Example Request:
curl -X GET "https://[your-domain]/api/genres"
Example Response:
{
  "genres": [
    {
      "name": "Fiction",
      "count": 238
    },
    {
      "name": "Drama",
      "count": 112
    },
    {
      "name": "Poetry",
      "count": 87
    }
  ]
}

Authors

GET /api/authors

Returns a list of all authors in the database with book counts.

Example Request:
curl -X GET "https://[your-domain]/api/authors"
Example Response:
{
  "authors": [
    {
      "name": "William Shakespeare",
      "book_count": 37
    },
    {
      "name": "Mark Twain",
      "book_count": 24
    },
    {
      "name": "Charles Dickens",
      "book_count": 22
    }
  ]
}

Time Periods

GET /api/time-periods

Returns available time periods by century with book counts.

Example Request:
curl -X GET "https://[your-domain]/api/time-periods"
Example Response:
{
  "time_periods": [
    {
      "name": "16th Century",
      "century": 16,
      "start_year": 1501,
      "end_year": 1600,
      "book_count": 18
    },
    {
      "name": "19th Century",
      "century": 19,
      "start_year": 1801,
      "end_year": 1900,
      "book_count": 342
    }
  ]
}

Stats (Authenticated Users Only)

GET /api/stats

Returns statistics about the database (requires authentication).

Example Request:
curl -X GET "https://[your-domain]/api/stats" -H "Authorization: Bearer YOUR_TOKEN"
Example Response:
{
  "total_books": 1250,
  "total_excerpts": 48920,
  "unique_authors": 315,
  "unique_genres": 42,
  "avg_excerpts_per_book": 39.14
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests. Error responses include an error field with a description.

Example Error Response (404 Not Found):
{
  "error": "No excerpts found matching the specified criteria",
  "status": 404
}
Common Status Codes:
Status Code Description
200 OK - Request succeeded
400 Bad Request - Invalid parameters
401 Unauthorized - Authentication required
404 Not Found - Resource not found
500 Internal Server Error - Server encountered an error