api.redecapivara.social

API service for Rede Capivara social platform that provides Open Graph metadata extraction from URLs.

Overview

This is a lightweight Starlette-based API that scrapes and extracts Open Graph metadata from web URLs. It's designed to support link preview functionality for the Rede Capivara social network.

Features

• Open Graph metadata extraction
• Fallback to basic HTML metadata when OG tags are unavailable
• Rate limiting (10 requests per minute per IP)
• Response caching (10 minutes TTL)
• CORS enabled for all origins
• Async/await architecture for efficient handling

Requirements

• Python 3.11.11 or higher
• Docker and Docker Compose (optional)

Installation

Using uv (recommended)

# Install dependencies
uv sync

Running the API

Local Development

uv run uvicorn src.app:app --host 0.0.0.0 --port 8080 --reload

Using Docker Compose

docker compose up

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

API Endpoints

GET /api/card

Extracts Open Graph metadata from a given URL.

Query Parameters:

• url (required): The URL to extract metadata from

Example Request:

curl "http://localhost:8080/api/card?url=https://example.com"

Example Response:

{
  "title": "Example Domain",
  "description": "Example website description",
  "image": "https://example.com/image.jpg",
  "url": "https://example.com"
}

Error Responses:

• 400 Bad Request: Missing URL parameter
• 500 Internal Server Error: Failed to fetch data from URL

Technology Stack

• Starlette: Async web framework
• httpx: HTTP client for async requests
• BeautifulSoup4: HTML parsing
• aiocache: Response caching
• slowapi: Rate limiting middleware
• uvicorn: ASGI server

Development

Project Structure

api.redecapivara.social/
├── src/
│   ├── app.py              # Main application and routes
│   └── services/
│       └── scraper.py      # URL scraping service
├── pyproject.toml          # Project dependencies
├── Dockerfile              # Container definition
└── docker-compose.yml      # Docker orchestration

Rate Limiting

The API implements rate limiting of 10 requests per minute per IP address to prevent abuse.

Caching

Responses are cached for 10 minutes to reduce load on external websites and improve response times.

License

See LICENSE file for details.