Getting Started

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

Prerequisites

• Python 3.8+
• pip (Python package manager)

Installation

1. Clone the repository and navigate to the project directory.
2. Install the required dependencies:

pip install -r requirements.txt

Hello World / Quick Start

Running the Server

To start the API server in development mode:

python run.py

The server will start on http://localhost:5000.

Basic API Usage

Once the server is running, you can create your first bookmark using curl:

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

Using the Service Layer

If you are extending the application, you can interact with the BookmarkService directly. It handles validation, caching, and search indexing automatically.

from app.services.bookmark_service import BookmarkService

# BookmarkService is a singleton
service = BookmarkService()

# Create a bookmark
bookmark, error = service.create_bookmark({
    "url": "https://python.org",
    "title": "Python Language",
    "description": "Official Python website"
})

if bookmark:
    print(f"Created bookmark: {bookmark.id}")
else:
    print(f"Error: {error}")

# List active bookmarks
bookmarks, total = service.list_bookmarks(page=1, per_page=10, status="active")

Configuration

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

Variable	Description	Default
SECRET_KEY	Secret key for Flask session signing	change-me
FLASK_ENV	Environment mode (development, production, testing)	development

The application uses different configuration classes defined in app/config.py:

• DevelopmentConfig: Enables debug mode and smaller page sizes.
• ProductionConfig: Requires a SECRET_KEY to be set in the environment.
• TestingConfig: Used for running automated tests.

Verify Installation

You can verify that the API is running correctly by checking the internal health endpoints:

# Check liveness
curl http://localhost:5000/_internal/health

# Check readiness (verifies service initialization)
curl http://localhost:5000/_internal/ready

Next Steps

• Organize with Tags: Learn how to use the Tagging and Categorization to categorize your bookmarks.
• Group into Collections: Use Managing Collections to group related bookmarks together.
• Search: Utilize the Implementing Full-Text Search capabilities to find bookmarks by title or description.
• Caching: Understand how the Service Architecture and Caching Strategy improves performance for frequently accessed items.

Troubleshooting

Connection Pool Exhausted

If you see a RuntimeError: Connection pool exhausted, it means the internal _ConnectionPool has reached its limit. In this test implementation, this usually indicates that connections are not being released properly in the repository layer.

Validation Errors

The API performs strict validation on URLs and titles. Ensure that:

• URLs start with http:// or https://.
• Titles are not empty and do not exceed length limits.