Skip to main content

EtchBlok Test API Documentation

A powerful, in-memory REST API for managing and organizing bookmarks, tags, and collections.

Overview​

Welcome to the EtchBlok Test API! This project provides a complete, feature-rich backend service for a modern bookmarking application. It's designed with a clean, layered architecture that separates API routes, business logic, and data persistence, making it a perfect reference for building robust Flask applications.

At its core, EtchBlok is more than just a simple link saver. It allows you to organize bookmarks with flexible tags, group them into smart and manual collections, and find them instantly with a built-in full-text search engine. Because it uses an in-memory database, it's incredibly fast and easy to get up and running for testing, development, or as the foundation for your next knowledge management tool.

Key Concepts​

  • Core Data Models Understanding the Core Data Models: The heart of the API revolves around three main entities: Bookmarks, Tags, and Collections. Understanding how they relate to each other is the first step to mastering the API.
  • In-Memory Persistence Introduction to the Bookmark Repository: All data is stored in memory, which means the API is blazing fast and requires no external database setup. This also means data is ephemeral and will be reset when the application restarts.
  • The Service Layer Introduction to BookmarkService: A central facade that contains all the business logic. It coordinates operations between the data repository, search index, and cache, ensuring data integrity and providing a clean interface for the API endpoints.
  • Full-Text Search Overview of Full-Text Search: Go beyond simple filtering with an in-memory inverted index that provides fast and relevant search results across your bookmark titles and descriptions.
  • Smart Collections Organizing Bookmarks with Collections: Automatically group bookmarks into "smart" collections based on filter rules. For example, create a collection that dynamically includes any bookmark containing the word "Python".

Common Use Cases​

  • Powering the backend for a personal bookmarking web application or browser extension.
  • Serving as a reference architecture for building a well-structured Flask REST API.
  • Prototyping and testing applications that require bookmark management features.
  • Integrating a lightweight link organization service into a larger application, like a team wiki or a research tool.

Getting Started​

Ready to dive in? We recommend starting with the Getting Started guide for a quick setup. After that, familiarize yourself with the Understanding the Core Data Models to learn about the resources you'll be working with. From there, you can explore the API endpoints, starting with Working with Bookmarks, to begin creating and managing your data.