Skip to main content

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.

VariableDescriptionDefault
SECRET_KEYSecret key for Flask session signingchange-me
FLASK_ENVEnvironment 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​

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.