Skip to main content

Etchblok Test API

Your personal bookmarking service, delivered as a clean and powerful REST API.

Overview​

Welcome to the Etchblok Test API, a comprehensive and well-structured backend for a modern bookmarking application. This project provides a complete set of RESTful endpoints for managing bookmarks, organizing them with tags, and curating them into collections. It's designed to be a practical example of clean API architecture, featuring a clear separation of concerns between routing, business logic, and data persistence.

At its core, the API operates entirely in-memory, making it perfect for local development, prototyping, or as a reference for building your own stateful services. Beyond simple CRUD operations, it includes advanced features like a built-in full-text search engine, bookmark lifecycle management (active, archived, trashed), and "smart" collections that automatically group bookmarks based on filter rules. Whether you're building a front-end client or learning backend design patterns, this API provides a robust and feature-rich foundation.

Key Concepts​

  • Domain Models Domain Models: The core entities of the API are Bookmarks, Tags, and Collections. Understanding how these three resources interact is fundamental to using the system effectively.
  • Bookmark Lifecycle Managing Bookmark Lifecycle: A bookmark isn't just created and deleted; it moves through states. Learn about the active, archived, and trashed statuses that define a bookmark's visibility and availability.
  • The Service Facade Design Rationale: Singleton Facade: All business logic is orchestrated through a central BookmarkService. This singleton layer handles validation, coordinates repository actions, and ensures consistency across the application.
  • In-Memory Persistence The Repository Architecture: The API uses an in-memory repository for all data storage. This means data is fast and easy to work with but is not persisted across application restarts.
  • Search & Indexing Overview of the Search System: Discover how the API provides powerful full-text search capabilities through an in-memory inverted index that is kept in sync with your bookmark library.

Common Use Cases​

  • Building a front-end client for a personal bookmarking application (like Pocket or Instapaper).
  • Learning and experimenting with modern REST API design patterns in a Python environment.
  • Prototyping features for a content management or knowledge base system.
  • Integrating bookmark-saving and organization capabilities into a browser extension or third-party application.

Getting Started​

Ready to dive in? We recommend starting with the Getting Started guide to set up your local environment. Once you're up and running, follow the Building a Bookmark Library tutorial to make your first API calls. From there, you can explore more advanced topics like Organizing with Tags and Collections and Performing Text Searches.