QuoteSlate

<h1 align="center">QuoteSlate API</h1> <div align="center">

A robust, developer-friendly API for serving inspirational and thought-provoking quotes with powerful filtering capabilities.

Explore the API | Documentation | Deploy Your Own

</div>

---

📚 Table of Contents

• Overview
• Using QuoteSlate Responsibly
• Features
• Getting Started
  • Quick Start
  • Deploying on Vercel
  • Running Locally
• API Reference
  • Endpoints
  • Parameters
  • Response Format
• Usage Examples
• Error Handling
• Rate Limiting
• Technical Details
• Testing
• Contributing
• Projects Using QuoteSlate
• License

---

Overview

QuoteSlate API is a lightweight, high-performance API that provides access to a curated collection of 2,600+ inspirational quotes. Built as an open-source RESTful service, it offers flexible filtering options, making it perfect for applications ranging from personal development apps to educational platforms.

Base URL: https://quoteslate.vercel.app

---

Using QuoteSlate Responsibly

The QuoteSlate API is a labor of love, provided free of charge to support the developer community. My goal is to keep it open and accessible to everyone, especially for hobby projects and creative applications. It's currently hosted on Vercel's free plan, which generously provides resources for small-scale projects. However, to ensure its long-term sustainability for everyone, I ask for your cooperation in using the API responsibly.

Here's how you can help:

1. Optimize Your Requests and Cache Quotes

Please make use of the count parameter to fetch multiple quotes (up to 50) in a single request whenever possible. This significantly reduces the load on the server.

Furthermore, cache the quotes you fetch locally in your application. For example, if your app displays 5 quotes per day, fetching and caching 50 quotes means you'll have enough for 10 days without needing to make another API call. This not only reduces server load but also makes your app more resilient – if the API experiences downtime, your app can continue functioning using the cached quotes.

2. Commercial or Public Use? Deploy Your Own

I understand the temptation to use the default endpoint (quoteslate.vercel.app) – it's definitely the easiest option. However, this endpoint is designed for hobbyists creating projects primarily for their own use or very small-scale applications.

If your project is commercial, intended for public use, or will generate a significant number of API calls, it is crucial that you fork this repository and deploy your own instance on Vercel. It's easy and free for most use cases! This gives you dedicated resources, ensures you won't be impacted by rate limits, and helps keep the public endpoint sustainable for everyone.

For very high-volume applications, you can even create multiple deployments on Vercel and implement load balancing on your app's end to distribute requests across them. Think of QuoteSlate as our project, not just mine. If you are building something that requires a lot of requests, take ownership and deploy your instance. Detailed instructions are in the Deploying on Vercel section.

3. Give Credit Where It's Due

I don't ask for payment, but proper attribution is essential. If you use the QuoteSlate API in your project, please include a brief acknowledgment, such as:

"Quotes powered by the QuoteSlate API"

or

"This project uses the QuoteSlate API, a free and open-source quote API. Check it out here"

4. Show Your Support

A simple star ⭐ on this GitHub repository goes a long way in helping others discover the project and growing the community.

Why This Matters

By following these guidelines, you help me keep the QuoteSlate API free and available for everyone. While Vercel's free plan is currently sufficient, a large number of individual requests puts a strain on those resources. If usage patterns don't change, I might have to upgrade to a paid plan, which would be a financial burden.

Thank you for your understanding and cooperation in making the QuoteSlate API a valuable resource for the entire community!

---

Features

Core Functionality

• 🎲 Random Quote Generation - Fetch random quotes from a diverse collection
• 📦 Bulk Retrieval - Get up to 50 quotes in a single request
• 🔍 Advanced Filtering - Filter quotes by author, length, and tags
• 📊 Metadata Access - Retrieve complete lists of authors and tags
• 🔄 Regular Updates - Continuously curated and improved quote database

Technical Features

• ⚡ High Performance - Optimized for quick response times (<100ms)
• 🛡️ Rate Limiting - 100 requests per 15 minutes per IP
• 🌐 CORS Support - Access from any origin
• 🔒 Input Validation - Robust parameter validation and sanitization
• 📝 Detailed Error Messages - Clear, actionable error responses
• 🔄 RESTful Architecture - Clean, predictable API endpoints
• 📖 Open Source - Fully transparent and community-driven
• 📘 OpenAPI Documentation - Specification available at /api/openapi.json

---

Getting Started

No API key is required. Simply make HTTP requests to the endpoints using your preferred method.

Quick Start Example

// Retrieve a random quote
fetch('https://quoteslate.vercel.app/api/quotes/random')
  .then(response => response.json())
  .then(data => console.log(data));

Deploying on Vercel (Easiest for High-Volume Needs)

If your project is commercial, intended for public use, or requires a large number of API calls, deploying your own instance on Vercel is strongly recommended. Here's how:

One-click Deploy

Manual Deployment

1. Fork the Repository - Click the "Fork" button at the top right of this repository
2. Go to Vercel Dashboard - Log in to your Vercel account (or create one – it's free!)
3. Create a New Project - Click the "New Project" button
4. Import Your Forked Repository - Select your forked QuoteSlate repository
5. Configure the Project - Keep the default settings (Vercel auto-detects Node.js)
6. Deploy! - Click "Deploy" and Vercel will build and deploy your API
7. Your Own Endpoint - You'll receive a unique URL for your instance
8. (Optional) Multiple Deployments - For very high volume, create multiple deployments and implement load balancing

It's that simple! Vercel handles all the complexity of hosting and scaling for you. For detailed instructions, refer to Vercel's documentation.

Running Locally

Follow these steps to run the API on your local machine:

Prerequisites

• Node.js (v14 or higher)
• npm (Node Package Manager)

Installation Steps

1. Clone the Repository

   git clone https://github.com/Musheer360/QuoteSlate.git
   cd QuoteSlate
   

2. Install Dependencies

   npm install
   

3. Verify Data Files

   Ensure you have the following JSON files in the data/ directory:

   • quotes.json - Contains the quotes data
   • authors.json - Contains author names and their quote counts
   • tags.json - Contains available tags

4. Start the Server

   npm start
   

   The API will be available at http://localhost:3000

5. Test the Installation

   curl http://localhost:3000/api/quotes/random
   

Data File Formats

The JSON files in the data/ directory follow these formats:

data/quotes.json:

[
  {
    "id": 1,
    "quote": "Quote text here",
    "author": "Author Name",
    "length": 123,
    "tags": ["tag1", "tag2"]
  }
]

data/authors.json:

{
  "Author Name": 5,
  "Another Author": 3
}

data/tags.json:

["motivation", "wisdom", "life"]

---

API Reference

An OpenAPI specification is available at /api/openapi.json.

Endpoints

1. Random Quotes

GET /api/quotes/random

Retrieve one or more random quotes with optional filtering.

2. Author List

GET /api/authors

Returns an object with author names as keys and their quote counts as values.

Response format:

{
  "Avery Brooks": 1,
  "Ayn Rand": 3,
  "Babe Ruth": 4
}

3. Tags List

GET /api/tags

Returns an array of all available tags.

Response format:

[
  "motivation",
  "inspiration",
  "life",
  "wisdom"
]

Parameters

All parameters are optional and can be combined for advanced filtering.

| Parameter | Type | Range/Limit | Description | Example | |-------------|---------|-------------|------------------------------------------------------|-----------------------------------| | authors | string | Max 20 | Comma-separated list of author names (c