Getting Started

Pagemark API is a bookmark management service built with Flask. It provides a layered architecture for managing bookmarks, tags, and collections with built-in caching and full-text search.

Prerequisites

• Python 3.8+
• pip (Python package installer)

Installation

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

   git clone <repository-url>
   cd pagemark-api

2. Create and activate 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. Start the API Server

Run the application using the provided entry point:

python run.py

The server will start on http://localhost:5000 with debug mode enabled.

2. Create Your First Bookmark

Open a new terminal and use curl to save a bookmark:

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

3. List All Bookmarks

Retrieve your saved bookmarks:

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

Configuration

The application uses environment variables for configuration. These are managed in app/config.py.

Variable	Description	Default (Dev)
SECRET_KEY	Used for session security. Required in production.	change-me
PAGE_SIZE	Default number of items per page for list endpoints.	10

To set a secret key in your environment:

export SECRET_KEY="your-secure-random-string"

Verify Installation

You can verify that the service and its internal components (repository, search index) are correctly initialized by hitting the internal health endpoints:

# Basic liveness check
curl http://localhost:5000/_internal/health

# Readiness check (verifies service initialization)
curl http://localhost:5000/_internal/ready

Next Steps

• Organize with Tags: Learn how to create and attach tags to your bookmarks using the Tagging System.
• Group into Collections: Use the Grouping with Collections to group related bookmarks together.
• Search: Utilize the Performing Text Searches capabilities to find bookmarks by title or description.
• Architecture: Explore the Architecture Overview (Routes -> Services -> Repository) to understand how the data flows.

Troubleshooting

• Port 5000 already in use: If you encounter an error stating the port is occupied, you can change the port in run.py or stop the conflicting process.
• Missing SECRET_KEY: In production mode, the application will fail to start if SECRET_KEY is not set in the environment. Ensure it is exported before running the server.
• Validation Errors: The API validates URLs and titles. Ensure your POST requests include a valid url (starting with http/https) and a non-empty title.