Skip to main content

Getting Started with Bookmark Management

This tutorial walks you through using the BookmarkService in etchblok-test-api to manage your bookmarks. You will learn how to initialize the service, create a validated bookmark, and retrieve it for display.

Prerequisites​

To follow this tutorial, ensure your environment is set up and you can import the app package. The BookmarkService automatically initializes its own dependencies, including the BookmarkRepository and SearchIndex.

Step 1: Initialize the BookmarkService​

The BookmarkService is implemented as a singleton. This ensures that stateful components, like the internal LRU cache, are shared across your entire application (e.g., between different Flask blueprints).

from app.services.bookmark_service import BookmarkService

# Calling the constructor always returns the same instance
service = BookmarkService()

Step 2: Create a Validated Bookmark​

To create a bookmark, pass a dictionary containing at least a url and a title to the create_bookmark method. The service performs validation using internal rules defined in app.models._validators.

The method returns a tuple: (Bookmark, None) on success, or (None, error_message) on failure.

bookmark_data = {
    "url": "https://github.com/example/project",
    "title": "Example Project",
    "description": "A very useful repository for testing."
}

bookmark, error = service.create_bookmark(bookmark_data)

if error:
    print(f"Failed to create bookmark: {error}")
else:
    print(f"Created bookmark with ID: {bookmark.id}")

In etchblok-test-api, validation fails if:

  • The url does not match the standard HTTP/HTTPS pattern.
  • The title is missing or exceeds 256 characters.

Step 3: Retrieve a Bookmark​

Once a bookmark is created, you can retrieve it using its unique ID. The BookmarkService first checks its internal LRUCache before querying the BookmarkRepository.

bookmark_id = bookmark.id  # From the previous step
retrieved = service.get_bookmark(bookmark_id)

if retrieved:
    print(f"Found: {retrieved.title} ({retrieved.url})")

Step 4: Serialize for API Responses​

The Bookmark object returned by the service is a domain model. To convert it into a format suitable for a JSON response, use the to_dict() method.

import json

if retrieved:
    # Convert the Bookmark model to a dictionary
    data = retrieved.to_dict()
    print(json.dumps(data, indent=2))

The resulting dictionary includes the bookmark's id, status (e.g., "active"), and timestamps:

{
  "id": "a1b2c3d4e5f6",
  "url": "https://github.com/example/project",
  "title": "Example Project",
  "description": "A very useful repository for testing.",
  "tags": [],
  "status": "active",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "metadata": {}
}

Complete Example​

Here is how these steps typically look when integrated into a route handler, similar to the implementation in app/routes/bookmarks.py:

from app.services.bookmark_service import BookmarkService

service = BookmarkService()

def add_new_resource(url, title):
    payload = {"url": url, "title": title}
    
    # 1. Create with validation
    bookmark, error = service.create_bookmark(payload)
    
    if error:
        return {"error": error}, 400
        
    # 2. Retrieve (demonstrating cache usage)
    refreshed = service.get_bookmark(bookmark.id)
    
    # 3. Return serialized data
    return refreshed.to_dict(), 201

# Usage
result, status_code = add_new_resource("https://example.com", "Example")
print(f"Status {status_code}: {result}")

Next Steps​