Getting Started

Pagemark API is a bookmark management REST API built with Flask. It provides a layered architecture for saving, organizing, and searching bookmarks with tagging and collections.

Prerequisites

• Python 3.8+
• pip (Python package manager)

Installation

1. Clone the repository (if you haven't already):

   git clone <repository-url>
   cd pagemark-api

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

Hello World / Quick Start

1. Run the Server

Start the Flask application using the provided entry point:

python run.py

The API will be available at http://localhost:5000.

2. Create Your First Bookmark

Use curl to save a new bookmark:

curl -X POST http://localhost:5000/api/bookmarks/ \
     -H "Content-Type: application/json" \
     -d '{"url": "https://flask.palletsprojects.com", "title": "Flask Documentation"}'

3. List Bookmarks

Retrieve all saved bookmarks:

curl http://localhost:5000/api/bookmarks/

Configuration

The application uses environment variables for configuration. You can set these in a .env file in the root directory.

Variable	Description	Default
SECRET_KEY	Used for session security and signing.	change-me
FLASK_ENV	Set to development or production.	development

Production Setup

For production, ensure you set a secure SECRET_KEY:

export SECRET_KEY=$(python -c 'import os; print(os.urandom(24).hex())')

Verify Installation

You can verify that the API is running and healthy by hitting the internal health endpoint:

curl http://localhost:5000/_internal/health

Expected response:

{"status": "ok"}

To check if the core services (Repository, Search Index) are ready:

curl http://localhost:5000/_internal/ready

Next Steps

• Explore the API: See the full list of endpoints in the Overview for tagging and collections.
• Search: Try the search endpoint at /api/bookmarks/search?q=flask.
• Architecture: Learn about the internal structure in the app/ directory, including app.services.bookmark_service.BookmarkService and app.db.repository.BookmarkRepository.