Skip to main content

EtchBlok Test API

A feature-rich, in-memory REST API for managing and organizing bookmarks.

Overview​

Welcome to the EtchBlok Test API, a complete and well-structured reference implementation for a modern bookmarking service. This project provides a robust backend for managing URLs, organizing them with tags and collections, and performing powerful full-text searches—all without the need for an external database.

Built with Flask, this API demonstrates best practices in application design, including a clean separation of concerns between the API routes, business logic, and data storage. Its in-memory architecture makes it incredibly fast and easy to get up and running, providing a perfect sandbox for developers to learn API design patterns, build front-end applications, or prototype new features for content management.

Key Concepts​

  • Domain Models Domain Model Architecture: The core entities of the API are Bookmarks, Tags, and Collections. Understanding how these three models interact is fundamental to using the system effectively. Each model is designed to be simple, extensible, and easy to work with.

  • Service-Repository Architecture Service Architecture and Caching: The API's logic is cleanly separated into a Service Layer for business rules (like validation and caching) and a Repository Layer for data access. This pattern makes the codebase maintainable, testable, and easy to understand.

  • Bookmark Lifecycle Managing Bookmark Lifecycle: Bookmarks aren't just created and deleted; they move through a lifecycle. A bookmark can be active, archived, or trashed, allowing for more sophisticated workflows than simple CRUD operations.

  • Smart Collections Manual vs. Smart Collections: Go beyond simple folders. Collections can be manual (you add bookmarks yourself) or smart (automatically populated based on a filter rule). This powerful feature enables dynamic, query-based organization of your content.

  • In-Memory Search & Storage Search System Architecture: The API uses an in-memory inverted index for lightning-fast full-text search across bookmark titles and descriptions. The entire data store is in-memory, which means no database setup is required to start developing.

Common Use Cases​

  • Building a front-end application for a personal bookmarking or "read-it-later" service.
  • Learning modern Python API design patterns, including the service-repository pattern and in-memory data management.
  • Prototyping and testing features for a larger content management system.
  • Understanding the fundamentals of building a simple, in-memory search engine.

Getting Started​

Ready to dive in? We recommend starting with the Getting Started guide to set up your environment. From there, follow the Your First Bookmark Operation tutorial to make your first API call. Once you're comfortable with the basics, explore how to Organizing with Tags and Collections to unlock the API's full organizational power.