Skip to main content

Pagemark API

Pagemark is a simple REST API for managing bookmarks. It's a self-hosted service, built with Flask, that lets you save, tag, search, and organize URLs programmatically. Think of it as a personal, API-first bookmarking engine.

Why Pagemark?​

Browser bookmarks are great for manual use, but they're locked inside the browser. If you want to build custom tools—like a "read-it-later" app, a personal knowledge archive, or an automated link-saving bot—you need an API.

Pagemark provides a clean, straightforward HTTP interface for your link collection. Instead of relying on a third-party service, you can run your own. It's designed as a simple, understandable foundation for personal projects and prototypes, without the complexity of a full-scale production system.

The easiest way to think about Pagemark is as a private digital library for your links. The entire library exists in memory, making it fast but temporary.

  • Bookmarks are the "books": The core item in your library. Each bookmark is a URL with a title, description, and some metadata.
  • Tags are "sticky notes": You can attach multiple tags (like python, learning, or api-design) to any bookmark to categorize it.
  • Collections are "shelves": A collection is a named group of bookmarks. You can have a manual shelf where you place bookmarks one-by-one, or a smart shelf that automatically includes any bookmark matching a search term (e.g., a "Flask" collection that contains any bookmark with "Flask" in its title).

How It Works​

Pagemark is a standard Flask application with a layered architecture. When you send an HTTP request, it flows through these layers:

  1. Routes: Flask endpoints receive the HTTP request (e.g., POST /api/bookmarks).
  2. Service Layer: Business logic validates the request, orchestrates operations, and manages the cache. For example, it ensures a new bookmark has a URL and title.
  3. Repository Layer: This layer abstracts the data storage. It provides a simple interface like save_bookmark() or get_tag().
  4. In-Memory Storage: The actual data is stored in Python dictionaries. This means all bookmarks, tags, and collections are lost when the application restarts.

Common Use Cases​

Here are a few examples of how to interact with the API using curl.

When to use: You've found a URL you want to save for later. Example:

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

List all your bookmarks​

When to use: You want to see everything you've saved. Example:

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

Search for a specific bookmark​

When to use: You need to find a link about a specific topic. Example:

curl http://localhost:5000/api/bookmarks/search?q=python

Create a new tag​

When to use: You want to create a new category to organize your links. Example:

curl -X POST http://localhost:5000/api/tags \
  -H "Content-Type: application/json" \
  -d '{"name": "python-libraries", "color": "blue"}'

When to Use Pagemark​

Pagemark is a great fit for certain scenarios and not for others.

Use It For...Don't Use It For...
✅ Personal projects and prototypes.❌ Production systems that need data to survive restarts.
✅ Building a custom "read-it-later" client or knowledge base.❌ Multi-user applications (it has no authentication).
✅ A learning tool for understanding Flask, REST APIs, and layered design.❌ Storing critical, irreplaceable data.
✅ A simple, self-hosted backend for a browser extension.❌ Services requiring high availability or large scale.

Integrations​

Pagemark is a standalone web service.

  • Clients: You can interact with it from any language or tool that can make HTTP requests (e.g., Python's requests, JavaScript's fetch, Postman, curl).
  • Dependencies: It's a Python application built on Flask. It has no external database or message queue dependencies.
  • Configuration: Basic settings can be configured using a .env file.

Getting Started​

You can get a local instance running in three steps:

  1. Clone the repository (not shown).
  2. Install dependencies: 
    pip install -r requirements.txt
  3. Run the server: 
    python run.py

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

Limitations & Assumptions​

Pagemark is intentionally simple. Be aware of these limitations:

  • In-Memory Storage Only: All data is stored in memory and will be permanently lost if the server process stops or restarts. There is no database.
  • Single-User Design: The API has no concept of users, authentication, or permissions. All data exists in a single, global namespace.
  • Simple Search: The full-text search uses a basic in-memory inverted index. It is suitable for small collections but is not as powerful as a dedicated search engine like Elasticsearch.

Frequently Asked Questions​

1. How is my data stored? Your data is stored in Python dictionaries inside the running application's memory. It is not written to a file or a database, so it does not persist.

2. What happens if the server restarts? All bookmarks, tags, and collections will be gone. The service will start with a completely empty state.

3. Is this API secure? Can I expose it to the internet? The API has no authentication or authorization. Anyone with network access to the service can read, add, and delete data. It is not recommended to expose it directly to the public internet without a security layer in front of it.

4. How can I add a real database like SQLite or PostgreSQL? You would need to modify the BookmarkRepository class in app/db/repository.py. Instead of using dictionaries, you would implement methods that interact with your chosen database using a library like SQLAlchemy.

5. What are "smart" collections? A smart collection automatically includes any bookmark that matches a simple text filter. For example, if you create a smart collection with the filter rule "API", any bookmark with "API" in its title or description will automatically appear in that collection.