Noctua Forest API

RESTful API for accessing our curated book collection

Base URL: https://noctuaforest.com/api

Authentication

The Noctua Forest API is currently public and does not require authentication. All endpoints are read-only and rate-limited to ensure fair usage.

Rate Limit: 100 requests per minute per IP address

Books

GET /api/books

Retrieve a list of books with optional filtering and search capabilities.

Query Parameters:

language (string) - Filter by book language (e.g., "English")
region (string) - Filter by author region (e.g., "Spain")
author (string) - Filter by author name (partial match)
tag (string) - Filter by genre/tag (e.g., "Fiction")
search (string) - Search across title, author, description, and tags
limit (number) - Maximum number of results (default: 50, max: 100)

Example Request:

GET /api/books?tag=Fiction&limit=10

Example Response:

{
  "success": true,
  "count": 2,
  "total": 3,
  "books": [
    {
      "id": "whispers-in-the-wind",
      "title": "Whispers in the Wind",
      "author": "Elena Rodriguez",
      "blurb": "A haunting tale of love and loss...",
      "tags": ["Historical Fiction", "Romance", "Spain"],
      "language": "English",
      "region": "Spain",
      "rating": 4.7,
      "publicationYear": 2023,
      "coverUrl": "/images/book-covers/whispers-wind.jpg"
    }
  ]
}

GET /api/books/{id}

Retrieve detailed information about a specific book.

Path Parameters:

id (string) - Unique book identifier

Example Request:

GET /api/books/whispers-in-the-wind

Example Response:

{
  "success": true,
  "book": {
    "id": "whispers-in-the-wind",
    "title": "Whispers in the Wind",
    "author": "Elena Rodriguez",
    "blurb": "A haunting tale of love and loss set against...",
    "tags": ["Historical Fiction", "Romance", "Spain"],
    "language": "English",
    "region": "Spain",
    "rating": 4.7,
    "publicationYear": 2023,
    "coverUrl": "/images/book-covers/whispers-wind.jpg"
  }
}

Error Handling

The API uses standard HTTP status codes and returns JSON error responses:

404 Not Found

{ "success": false, "error": "Book not found" }

500 Internal Server Error

{ "success": false, "error": "Failed to fetch books" }

429 Too Many Requests

{ "success": false, "error": "Rate limit exceeded" }

Usage Examples

JavaScript (Fetch API)

// Get all books
fetch('https://noctuaforest.com/api/books')
  .then(response => response.json())
  .then(data => console.log(data.books));

// Search for thriller books
fetch('https://noctuaforest.com/api/books?tag=Thriller')
  .then(response => response.json())
  .then(data => console.log(data.books));

// Get specific book
fetch('https://noctuaforest.com/api/books/midnight-calculations')
  .then(response => response.json())
  .then(data => console.log(data.book));

cURL

curl "https://noctuaforest.com/api/books?search=mathematics&limit=5"

Need Help?

Have questions about the API or need additional endpoints?